专栏首页大数据文摘怎么写一个超棒的README文档

怎么写一个超棒的README文档

大数据文摘出品

来源:medium

编译:青柠

如果你很着急、只是想要模板,可以直接跳到底部(但这样一点不酷),准备酷的人,迈出成为README大师的第一步吧!(绝对不是点击诱饵)

假如你刚刚创建了很棒的项目,并在GitHub上共享了它。你认为现在你只需坐等世界告诉你这个项目有多酷。毕竟,在过去的一个月中,你为这个极具挑战性的项目付出了不懈的努力,对吗?

好吧,让我们退后一步,从检查项目的开发人员或用户的角度来看。尽管你知道自己的项目有多酷,也知道它是如何解决一个(直到你出现之前)尚未解决的紧迫问题,但是看你项目的人想知道你构建了一个什么样的世界。

如果没有人知道如何使用你的软件,那情况非常糟糕。

如果人们不知道你的软件是做什么的,就不会使用它或为它做出贡献,并且很可能会在开源软件的海洋中找到更清晰明了的东西。

这就是README文件的用处!

好的README文档就像是项目的外观。这是一个人在你的项目中首先要看的东西,它提供了软件的简要介绍。

美观实用的README文档可以使你的项目脱颖而出,并引起开发人员社区的关注。

这将帮助他们了解你的项目,以及它要如何使用、为什么他们应该做出贡献。

“哇,伙计!太棒啦!既然你知道这么多,为什么不告诉我们该怎么写……”

嘿,我不能说有一套具体的规则,你要努力遵守这些规则,而不是要努力写一个好的README。

它不是那样的。

我将分享我是如何为我的开源项目写README的,以及你在为项目编写README文件时应考虑的事项,这样你将(有希望)收获一些见解。

GitHub链接:

https://github.com/navendu-pottekkat

另外请记住,你不会一天之内就精通撰写README。像所有事物一样,它需要实践。

我已经为开源贡献一段时间了,我注意到所有优秀的项目都有一个很棒的README。

当你位于项目界面时,你可以几分钟之内启动并运行你的项目版本。

有很多的贡献者、拉取请求、频繁发布的更新版本,都有一个很棒的README。

新的开发人员将能够找到所有详细信息以开始使用,例如安装说明和贡献指南。

新的用户将能够通过详细的屏幕截图和演示学会如何使用该项目。

“我没时间做这个,快给我看README!”

好吧,好吧,好吧(对不起我有点像麦康纳)。

以下是我的NSFW过滤项目的README,我认为这是我写过最好的README:

https://github.com/navendu-pottekkat/nsfw-filter/blob/master/README.md

我将介绍README的不同部分,这些部分对于每个README都是必不可少的。

下面是本例中使用的README文件的链接。你还可以找到一个模板README,并直接复制和粘贴到项目中:

https://github.com/navendu-pottekkat/awesome-readme/tree/master

项目标题

标题应具有自我解释性,尽量不要太拗口。 (当然存在例外,像本文“超棒的开源项目README编写指南”会是一个很酷的名字)

为你的README添加一个封面或横幅图片。为什么?因为它很容易引起人们的注意,而且看起来很酷。

等等,我忘了一件事。你可以将此链接的README用作模板:

https://towardsdatascience.com/media/README-template.md

横幅的最佳尺寸是1280x650px。你还可以将其用于repo的社交预览。

我个人使用Canva网站创建横幅图像。所有基本内容都是免费的(在大多数情况下,你不需要专业版)。

标题下那些华丽的东西是什么?

看起来不错吧?这些被称为徽章,它们通过提供一些快速见解提高了可读性,对吗?

你可以在你的项目中使用无数徽章,而且它们确实取决于项目。下面是我在每个项目中常用的一些。

我使用Shields IO网站制作徽章。这是一种简单易用的工具,你可以使用几乎所有的徽章:

https://shields.io

演示预览

写完项目后,最好对项目进行演示或预览(视频/ gif /屏幕截图都是不错的选择),以便人们知道你的项目中会有什么。你也可以在上一节中的演示中添加产品说明。

这是一个随机GIF作为占位符。

目录

在介绍了项目之后,添加目录是一个好主意。这将使人们可以更轻松地浏览你的README,并准确找到他们想要的内容。

这是一个示例目录(哇!太酷了!),实际上是本文的目录。

  • 项目标题
  • 演示预览
  • 目录
  • 安装
  • 使用方法
  • 发展
  • 贡献
    • 赞助
    • 添加新功能或修复错误
  • 许可证
  • 页脚

安装

你可能已经注意到了返回顶部的按钮(如果没有,请注意,它就在这里!)。这是一个好主意,因为它使README更易于浏览。

第一个问题应该是如何安装(如何使用项目或如何在机器中启动编辑)。

这里应该给用户详尽的想法,并说明他们如何使用项目repo的所有步骤。

按照以上步骤,他们应该能够在自己的设备中运行它。

我的方法是,完成README后,从头开始阅读这些步骤并检查是否有效。

这是一个示例指令:

要使用此项目,请首先使用以下命令在你的设备上克隆repo:

git init

git clone

GitHub链接:

https://github.com/navendu-pottekkat/nsfw-filter.git

用法

这部分是可选的,用于向用户提供安装后如何使用项目的信息,也可以添加到“安装”部分。

发展

在这里,你可以向开发人员说明如何修改代码。

你可以深入说明代码如何工作及所有内容如何组合在一起。

你还可以提供如何设置开发环境的具体说明。

理想情况下,你应该使README保持简洁。如果需要添加更复杂的说明,请使用Wiki:

https://github.com/navendu-pottekkat/nsfw-filter/wiki

贡献

在这里,你可以让人们知道他们如何为你的项目做出贡献。下面给出了一些方法。

这也显示了如何在节中添加子节。

赞助

你的项目备受青睐,并且已经被成千上万的人使用(有了这个README文件,将会有更高使用量)。现在,是时候寻找人员或组织来赞助你的项目了。

这可能是因为你没有从项目中获得任何收入,你需要钱来维持项目生存。

你可以在此部分中添加人们如何赞助你的项目。在此处添加你的patreon或GitHub赞助商链接,以方便访问。

一个好主意是还要向赞助商展示他们的组织徽标或徽章,向他们表达你的爱!(总有一天我会找到赞助商,并向他们表达我的爱)

添加新功能或修复错误

这是为了让人们了解如何在你的项目中提出问题或提出功能要求。

你还可以为项目提交、发布或拉取请求提供指导。

就个人和标准而言,你应该使用一个问题模板和拉取请求模板,以便用户打开新问题时可以按照项目指南轻松地格式化它:

https://github.com/navendu-pottekkat/nsfw-filter/blob/master/ISSUE_TEMPLATE.md

你还可以添加联系人详细信息,以便人们就你的项目与你取得联系。

许可证

将许可证添加到README是一个好习惯,这样人们可以轻松地引用它。

确保已在项目文件夹中添加了许可证文件。快捷方式:在GitHub中单击repo根目录下的添加新文件-->将文件名设置为LICENSE -->GitHub显示许可证模板--->选择最适合项目的模板!

我个人添加了许可证名称,并提供了指向它的链接,如下所示:

https://opensource.org/licenses/GPL-3.0

页脚

我们还可以添加一个页脚,因为我喜欢页脚,可以使用它来传达重要信息。

让我们将其制作为图像,因为到目前为止你已经意识到图像中的多媒体==酷(*请注意这个微妙的编程玩笑)。

就是这样……你已经完成了你的训练,小蚱蜢。现在是时候将这些想法用于你的项目了。

当你的项目与酷炫的README一起启动时,不要忘记README Sensei(很酷的推特处理想法)。

如果你认为有帮助,请在GitHub上标星号并共享本指南。

现在,你们一直在等待的时刻!页脚![喘气]

好吧,事情就这样结束了。

相关报道:

https://towardsdatascience.com/how-to-write-an-awesome-readme-68bf4be91f8b

本文分享自微信公众号 - 大数据文摘(BigDataDigest)

原文出处及转载信息见文内详细说明,如有侵权,请联系 yunjia_community@tencent.com 删除。

原始发表时间:2020-07-26

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

我来说两句

0 条评论
登录 后参与评论

相关文章

  • 直男福利!手把手教你做一只口红色号识别器,秒变李佳琦

    快乐橙、伤心紫,姨妈红,鸡屎绿…直男眼里没什么区别的颜色,在女生眼里各种色调、质地细微的区别都能分析一清二楚。

    大数据文摘
  • 耶鲁开发“进击的黏土”!穿两层衣服就变身机器人:给自己捏形状,还能越障

    除了施瓦辛格的那句经典台词,“I will be back”,看过第二部的小伙伴应该都记得这个经典的场景。

    大数据文摘
  • 滴滴柳青:算法和数据才是核武器

    大数据文摘
  • README 驱动开发

    最近,我又挖了几个开源项目的坑,Ledge、Ledge Framwork、Igso 等等。每次挖新坑的时候,经常性地都要花很多的时间,想着怎么编写 README...

    Phodal
  • 绘制热图

    colormap <- colorRampPalette(rev(brewer.pal(n = 7, name = "RdYlBu")))(100)

    爱学习的小明明
  • centos7如何添加开机启动项?

    1.系统服务管理命令,如果是通过yum安装的软件,开机启动脚本,已经自动创建好了,直接执行如下命令

    超蛋lhy
  • 【Rust日报】2020-06-29 - cargo alias

    ANSSI(法国国家网络安全局),信息系统安全国家机构是一项法国服务,创建于2009年7月7日,负责计算机安全。国家网络安全局向国防和安全事务秘书长报告,以协助...

    MikeLoveRust
  • R语言绘图 | 调整ggplot2坐标轴标签排列顺序

    "ggplot2"是我们常用的绘图包,但是使用ggplot2绘图时,输出的坐标轴标签总是按照字母排序,无法使用我们输入文件中排列的顺序。今天小编就教大家解决这一...

    生信小王子
  • MySQL和Oracle行值表达式对比(r11笔记第74天)

    行值表达式也叫作行值构造器,在很多SQL使用场景中会看到它的身影,一般是通过in的方式出现,但是在MySQL和Oracle有什么不同之处呢。我们做几个简单的测试...

    jeanron100
  • LSM设计一个数据库引擎

    以 Mysql、postgresql 为代表的传统 RDBMS 都是基于 b-tree 的 page-orented 存储引擎。现代计算机的最大处理瓶颈在磁盘的...

    码哥字节

扫码关注云+社区

领取腾讯云代金券