一个项目的README是非常重要的；别人看到你的开源项目的时候第一个看到的就是README，同时README也常常是项目唯一的文档。你的README对于你的项目来说，就相当于一个公司的官方网站一样，就像网站需要注意很多用户体验一样，我们的README也应该从用户的角度出发。
这篇文章将告诉我们如何写一个友好的README-不论对于新手还是对你项目很了解的人来说，这个README都会非常有帮助同时可以满足开发者的需求。
我们会利用一个叫做"Paddington"的虚拟的库作为例子，分部分来讲解这些东西。让我们从头开始吧。
项目标题
毫无疑问，一个网站最上面一部分应该用来展示最重要的信息。我们可以把这个原则放在我们的README上。
所以什么才是最重要的东西呢？正如所起到的作用一样，项目名字是很重要的。所以我们先加上下面这些内容：
上面这个基本可以满足新用户的需求，但是README的头部也需要满足已存在的用户的需求，他们有一些很容易回答的问题。当我访问一个我很熟悉的项目的时候，我会想知道：
最新的版本的多少？
它构建通过了吗？
作为一个新用户，我也有一些容易回答的问题：
它是用什么语言写的？
它支持哪个语言版本？
它是否通过测试？
它采用哪种开源证书？
我们可以通过徽章来回答上面所有的问题！
我在项目描述下面加了一行徽章，单独一行不会占据很大的空间同时又能涵盖许多信息：
是不是很好看？我使用了一个叫做shields.io的服务，它提供了一致的徽章图标同时也提供了一个添加自定义徽章的方式，比如开源证书信息。
对于头部的最后一部分，如果项目足够简单的话，我们可以添加一个简单的例子。这对于新手理解你的项目是用来干什么的有很大帮助，就像项目描述一样。
我们在头部有限的空间里面涵盖了丰富的内容。好极了！现在我们需要看看一些更具体的问题。如果我们的README会变得很长，那么要导航到某个具体的内容就变得很困难，现在添加一个目录就变得很有意义。
目录
目录对于相对比较短的README来说也是很有用的。它解决了信息索引的需求，为用户提供了一些有帮助的跳转链接到文档的不同部分。
如果用户只想要看看使用说明，为什么要让他们滚动页面看到他并不需要的安装指南呢，更何况安装指南只有第一次使用项目的时候会用到。
必要条件
现在我们来到文档中对于新用户更有用的部分，我们要确保他们获取他们所需要的信息。这部分就是用来添加所有你项目的必要条件的地方：语言，语言版本，包管理工具，操作系统。
这些内容可以直接写上去或者通过列表来展示，明显列表更清晰一些。这对你来说也很有用，这可以帮你有效的减少因为缺少必要条件而提交的ISSUE的数量。
在写必要条件的时候，你应该假设从0基础开始使用你的项目。确保你添加了语言和包管理工具的相关链接，这样你也许能帮助到对于项目一无所知的新手。
用法
你的使用手册可能是你README中最重要的部分，如果没有这个很少人可以知道怎么用你的项目。
这部分可以用很多种方式来写，这取决于你项目的类型。你也许需要一个API手册，一个web接口或者一个命令行工具；有时需要不只一种。下面这个手册涉及到一个Javascript API，不过你可以把这个方式应用到其他的接口文档上。
首先我们需要提到如何获取代码，是通过clone代码还是利用包管理工具来安装。别忘了添加一些有用的链接，来提供一些便利。
当给一个API写文档的时候，尽量保持简单清晰。也就是说先写出接口的主要用例。这可以吸引第一次看的用户。在这个例子中，我们突出了方法的参数和返回类型，并附上的例子。越明确，就能给你减少越多的麻烦。
我们已经涵盖了我们的主要用例，同时指明一些边界用例以及用户在使用过程中会遇到的问题也是很有帮助的。这个可以作为使用手册的子章节放在使用手册的最后。试着包括一些有问题的用户会搜索的关键词。
贡献
这部分也是很重要的，这决定了是否会有用户来给你贡献代码。就算你有一个CONTRIBUTING文件，如果一个人没有Github或者开源的经验就很难找到它。这部分应该包括基本信息并且如果你有一个CONTRIBUTING文件应该加上一个链接。
增加一个关于如何运行测试和提交pull request的简单介绍，对你来说也很有用。这意味着你review pull request的过程会更加有效率。
支持和版本变化
一个关于项目支持状态的章节也是很有用的，特别是当你发布了很多个不同的主版本的时候。这部分对于一些要进行版本迁移的老用户来说非常有帮助。
一个完整的迁移指南对于README来说可能太长了，所以我在项目中加入了一个MIGRATION文件，同时在README中添加了链接。
如果你有一个对于老版本的支持计划，请突出他们。同时你也可以用一个简单的表格来列出主要的版本和他们支持的最后期限。
证书
最后你应该加一个版权信息以及一个项目所使用开源证书的链接。如果没有这些信息很多用户无法使用你的项目，特别是一些大企业。就算你的项目里面有一个LICENSE文件，添加一个证书的链接也是很有用的。
其他部分
我们上面介绍的内容并没有包括了README可以写的全部内容。我项目中还包括了其他内容包括：
+ 为什么？
如果你的项目做了一些其他项目已经做了的事情，或者特别复杂，提供一些解释也是很有帮助的。
+ 共有的问题
一个用来列出经常出现的问题的地方，可以减少重复打开的ISSUE。
+ 例子
一个指向例子的链接。
+ 变更日志
一个关于项目变更日志的描述。
一个完整的 README
现在我们已经拥有一个友好的README，你可以在这里看到所有内容。
我希望更多的人在写文档的时候可以考虑用户的需求，如果你觉得漏了什么请告诉我。我对于如何写好README的建议和想法很感兴趣。
原文地址：http://rowanmanning.com/posts/writing-a-friendly-readme/
博客地址：Bin Playground