怎么写一个超棒的 README 文档

ゝ一世哀愁。 2021-08-31 23:05 337阅读 0赞

点击上方 [Java后端][Java]，选择 设为星标

优质文章，及时送达

--------------------

**大数据文摘出品**

**来源：medium**

**编译：青柠**

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

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

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

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

![format_png][]

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

这就是README文件的用处！

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

![format_png 1][]

美观实用的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

![format_png 2][]

项目标题

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

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

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

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

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

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

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

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

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

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

https://shields.io

![format_png 3][]

演示预览

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

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

![format_png 4][]

在介绍了项目之后，添加目录是一个好主意。这将使人们可以更轻松地浏览你的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

--------------------

\-END-

如果看到这里，说明你喜欢这篇文章，请 转发、点赞。同时 标星（置顶）本公众号可以第一时间接受到博文推送。

**推****荐****阅****读**

***1. ***[竟有如此沙雕的代码注释！][Link 1]

***2. ***[我发现了 GitHub 的彩蛋！][GitHub]

***3.*** [滴滴开源了哪些有意思的项目？][Link 2]

***4. ***[为什么很多 Spring Boot 开发者放弃了 Tomcat][Spring Boot _ Tomcat]

![format_png 5][]

最近整理一份面试资料**《Java技术栈学习手册》**，覆盖了Java技术、面试题精选、Spring全家桶、Nginx、SSM、微服务、数据库、数据结构、架构等等。

获取方式：点“ **在看**，关注公众号 **Java后端** 并回复 **777** 领取，更多内容陆续奉上。

喜欢文章，点个在看 ![format_png 6][]

[Java]: http://mp.weixin.qq.com/s?__biz=Mzg2MjEwMjI1Mg%3D%3D&chksm=ce0da17bf97a286df119047a25b7de51621fe542816673bb4aa3ebd8ab97b09a86ed7db2e2ee&idx=3&mid=2247489272&scene=21&sn=ce74938072fc73a808d83ccb474db46d#wechat_redirect
[format_png]: /images/20210730/c0e7a969708e495e961f101f905abd4f.png
[format_png 1]: /images/20210730/03d19d99d7d94819aaf68b19156625d7.png
[format_png 2]: /images/20210730/742483b317064cc68a80103309904eaf.png
[format_png 3]: /images/20210730/443840b6c3554cf593b8c1acbcb3e015.png
[format_png 4]: /images/20210730/7031a1698c2d4d998ae461ae38d56690.png
[Link 1]: http://mp.weixin.qq.com/s?__biz=Mzg2MjEwMjI1Mg%3D%3D&chksm=ce0e40e2f979c9f42cbf15e53321f606ca3fef56890a4996d701292c7cd4afaf4655bdb018b4&idx=1&mid=2247497569&scene=21&sn=22fc8d2db2e97d4aa0bb09a77e593195#wechat_redirect
[GitHub]: http://mp.weixin.qq.com/s?__biz=Mzg2MjEwMjI1Mg%3D%3D&chksm=ce0e40e2f979c9f4e877a174e0d1175317b3c4e00cbc85b59dba9e3545fa53a960baf7ea957c&idx=2&mid=2247497569&scene=21&sn=9617dd590f4e7528393bbbf29cad9584#wechat_redirect
[Link 2]: http://mp.weixin.qq.com/s?__biz=Mzg2MjEwMjI1Mg%3D%3D&chksm=ce0e40cef979c9d81b735c212964d2aafec9e8f6c4c2b56c4325f55a14d691747e5ba67c78ba&idx=1&mid=2247497549&scene=21&sn=571cb7c8299601f02e7c0a0183fafdcb#wechat_redirect
[Spring Boot _ Tomcat]: http://mp.weixin.qq.com/s?__biz=Mzg2MjEwMjI1Mg%3D%3D&chksm=ce0e40cef979c9d8aceca590428e7bb66f5e517dc9c710e196448c3f005df799a2189555cfd8&idx=3&mid=2247497549&scene=21&sn=4ce35018e522059a4ca364db7ab84ea6#wechat_redirect
[format_png 5]: /images/20210730/680ea9be53cd49b3aec24a5ad6465cf0.png
[format_png 6]: /images/20210730/16e14c6af67e47369724c7e5b244faad.png