若是你很着急、只是想要模板，能够直接跳到底部（但这样一点不酷），准备酷的人，迈出成为README大师的第一步吧！（绝对不是点击诱饵）
假如你刚刚建立了很棒的项目，并在GitHub上共享了它。你认为如今你只需坐等世界告诉你这个项目有多酷。毕竟，在过去的一个月中，你为这个极具挑战性的项目付出了不懈的努力，对吗？
好吧，让咱们退后一步，从检查项目的开发人员或用户的角度来看。尽管你知道本身的项目有多酷，也知道它是如何解决一个（直到你出现以前）还没有解决的紧迫问题，可是看你项目的人想知道你构建了一个什么样的世界。
若是人们不知道你的软件是作什么的，就不会使用它或为它作出贡献，而且极可能会在开源软件的海洋中找到更清晰明了的东西。
好的README文档就像是项目的外观。这是一我的在你的项目中首先要看的东西，它提供了软件的简要介绍。
美观实用的README文档可使你的项目脱颖而出，并引发开发人员社区的关注。
这将帮助他们了解你的项目，以及它要如何使用、为何他们应该作出贡献。
“哇，伙计！太棒啦！既然你知道这么多，为何不告诉咱们该怎么写……”
嘿，我不能说有一套具体的规则，你要努力遵照这些规则，而不是要努力写一个好的README。
我将分享我是如何为个人开源项目写README的，以及你在为项目编写README文件时应考虑的事项，这样你将（有但愿）收获一些看法。
https://github.com/navendu-pottekkat
另外请记住，你不会一天以内就精通撰写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
标题应具备自我解释性，尽可能不要太拗口。
（固然存在例外，像本文“超棒的开源项目R
EADME编写指南”会是一个很酷的名字）
为你的README添加一个封面或横幅图片。为何？由于它很容易引发人们的注意，并且看起来很酷。
等等，我忘了一件事。你能够将此连接的README用做模板：
https://towardsdatascience.com/media/README-template.md
横幅的最佳尺寸是1280x650px。你还能够将其用于repo的社交预览。
我我的使用Canva网站建立横幅图像。全部基本内容都是免费的（在大多数状况下，你不须要专业版）。
看起来不错吧？这些被称为徽章，它们经过提供一些快速看法提升了可读性，对吗？
你能够在你的项目中使用无数徽章，并且它们确实取决于项目。下面是我在每一个项目中经常使用的一些。
我使用Shields IO网站制做徽章。这是一种简单易用的工具，你可使用几乎全部的徽章：
写完项目后，最好对项目进行演示或预览（视频/ gif /屏幕截图都是不错的选择），以便人们知道你的项目中会有什么。你也能够在上一节中的演示中添加产品说明。
在介绍了项目以后，添加目录是一个好主意。这将令人们能够更轻松地浏览你的README，并准确找到他们想要的内容。
这是一个示例目录（哇！太酷了！），其实是本文的目录。
你可能已经注意到了返回顶部的按钮（若是没有，请注意，它就在这里！）。这是一个好主意，由于它使README更易于浏览。
第一个问题应该是如何安装（如何使用项目或如何在机器中启动编辑）。
这里应该给用户详尽的想法，并说明他们如何使用项目repo的全部步骤。
个人方法是，完成README后，从头开始阅读这些步骤并检查是否有效。
要使用此项目，请首先使用如下命令在你的设备上克隆repo：
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
本文分享自微信公众号 - 追马Linux（zhuima_k8s）。
若有侵权，请联系 support@oschina.cn 删除。
本文参与“OSC源创计划”，欢迎正在阅读的你也加入，一块儿分享。
