[译] 如何编写友好的 README

写在最前面：
最近陆续把工做中积累的vue组件开源，在写组件的README的时候不知道该怎么能写得很友(bi)好(ge)一些，想起来以前看的这篇文件，很详细的介绍了写README的几个方面，因此翻译出来跟你们分享下，你们能够根据各自的项目状况来写本身的README。

一个项目的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