原标题：畅行 GitHub：怎么写一个超棒的 README 文档 来源：大数据文摘微信公众号

如果你很发急、只是想要模板，可以直接跳到底部（但如许一点不酷），准备酷的人，迈出成为 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 后，重新开始阅读这些步骤并查抄是否有用。

这是一个示例指令：

要使用此项目，请起首使用以下命令在你的装备上克隆

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 上标星号并共享本指南。

现在，你们一直在等候的时刻！页脚！[喘息]

好吧，事情就如许竣事了。