README 文档养成记

通常来说，当别人第一次接触你的项目时，首先要看的一定是你的 README 文档。因此，对你的项目来说， README 文档的重要性不亚于一个公司的公司主页。然而，越来越多的人正着力于优化网页的用户体验，但却鲜有人考虑将自己项目的 README 文件写得易读一些。

这篇文章就是为改变现状而生。它会指导你如何写出一篇友好、易读的 README ，从而满足广大开发者及用户的需求，使他们无论经验多少都能很快上手。

在这篇文章中，我们将虚构一个名叫“ Paddington ”的项目作为例子，并分章节向大家介绍如何写好一篇 README 文档。

工程介绍

在 Web 领域，“页面分界线”一直是让人争论不休的话题，许多网页设计者为了把他们认为的用户最想了解的所有信息放到网页的页面分界线以上（也就是俗称的第一屏）而绞尽脑汁。对于一个好的 README 文档来说也是如此，我们必须把最重要的东西放到 README 文档的“第一屏”。

那么对于一个 README 文档来说，什么东西是最重要的呢？那肯定是这个项目的名称和主要的功能啦。那该怎么写呢？如下图所示。

当然第一屏的内容大多是为从未接触过该项目的人所准备的，但是 README 文档的最开头的几行同样要为老用户们服务。因为对于老用户来说，他们通常想通过你的 README 文件了解一些常见问题，比如该项目的最新版本，或者是该项目是否还在继续开发。

但是，如果作为一个刚接触这个项目的人，那么除了上面的两项，我还有类似以下的一些问题需要通过 README 文件了解：

• 这个项目是基于什么语言编写的
• 这个项目支持哪个版本的语言规范
• 这个项目已经经过测试了么
• 这个项目的许可类型是什么

这些东西对于一个 README 文件来说也十分重要，但是如果将这些问题一股脑儿全都用文字叙述的方法放到 README 的前几行，就会使 README 文档看起来杂乱不堪。但还好，我们有“标签”这种神奇的东西。

如图所示，我在项目简介下面加了一行五颜六色的标签。这些标签十分清晰的列出了几乎所有我们想知道的东西，同时又避免了纯文字描述的枯燥和杂乱。

作为 Heading 的最后一个部分，如果你的项目的功能可以用一个简单的例子来展示的话，那么我建议你最好在标签的下面加上这个例子。因为这同样有助于新用户快速了解你的项目能干什么。可以说它跟上面的项目简介具有同等重要的地位。

在上面的教程中，我们用很少的篇幅清晰地完成了对项目的概括。现在，所有人都能通过这小小几行字了解你的项目，我们不得不说，干得漂亮！

但是，一篇 README 要做的可不仅仅是这些，接下来，我们将面对用户们在使用中可能遇到的更多，更具体的问题。当然，作为一个 README 文件，我们必须尽可能周全的考虑到所有的问题并列出解决办法，但是这样无疑会使我们的 README 文件变得“又臭又长”。一个明智的办法便是建立目录。

目录

即使是在一个相对短的 README 中，目录也是非常有用的。它简化了信息的搜索，给用户提供了一些快速跳转到你文档中的不同部分的链接。

如果用户只是想看看帮助文档，那他们就没有必要先浏览一遍安装指南。当用户第一次接触你的项目的时候，什么才是最有用的？

必要条件

我们现在谈论的将是对新用户来说最有帮助的东西了，让用户获取到他们真正需要的东西。在这里，你可以写上任何你项目所需要的条件了。比如语言环境、语言版本、包管理系统、操作系统等。

只要能表达清楚，必要条件可以以列表或散文的形式给出。这对自己也是有帮助的，这意味着将会出现更少的兼容性错误。

你应该假设用户不具备任何的相关知识，确保所要求的语言和包管理工具都给出了链接。

使用方法

你的使用文档可能是你的 README 中最重要的部分了，却少它的话很少人会通过阅读你的代码来学习如何使用。

首先我们需要让用户知道如何获取代码，通过 Git 克隆或是包管理工具安装。别忘了链接上任何有用的信息，以防用户在拉取过程中出现问题。

在提供 API 时，使之尽量简洁易用。换言之，把主要用例写在前面。这保证了他人在第一次使用时注意点能更加集中。就我们而言，我们给出了方法所需要的参数及其返回的值，还有理想的用例。你表达的越清楚，遇到的问题就越少。

当我们介绍完理想用法之后，列出用户可能会遇到的问题以及一些边界值也是相当有帮助的。这可以是你文档最后的一小部分，主要面向已经安装并使用过你的项目的用户。尝试着解释一些可能使用户困惑或需要搜索的关键字。

贡献

这一部分对于 README 文档来说是很重要的，并且也是区分使用者和开发者的重要依据。即使你的项目中有一个 CONTRIBUTING 文档，但如果你的使用者们没有使用 Github 和开源项目的经验的话，他们很有可能找不到它。所以，本节除了包含一些基本内容之外，如果你的项目有一个 CONTRIBUTING 文档，你需要在这里放置它的链接。

你也可以在此处举例说明如何测试并生明 Pull Request 的正确格式。这将会使你的工程变得更加的规整有序。

如果你的项目有一个面向开发者的向导文档，那么你应该在这里放置它的链接。这样可以使刚接触你的项目的开发者感受到莫大的方便，并且尽可能保证所以的问题都会得到解决。

兼容性和可移植性

在你的工程里面兼容性还是显得非常重要的，尤其是当你版本有了一些重要的更新时。这一部分对于现在正在使用你的项目而且急需升级指导的用户们来说极其重要。

或许将一份详细的移植指导写进你的 README 文档里会显得有些啰嗦，所以我们可以在我们的项目根目录中放置了一份 MIGRATION 文档，并且在这里放置了一个指向它的链接，方便有需要的用户阅读。（这里是一个例子）

如果你打算兼容旧版本，你应该在这里做出说明。你也可以简单地通过一个表格来说明他们的最终版本和停止支持日期。

版权

在 README 文件的最后你应该加上许可信息并添加一个指向具体许可文件的链接。如果没有这部分内容，许多使用者，特别是大规模的企业级用户将无法使用你的工程。就算你将把 LICENSE 文件全都放在你的项目中，在这里这个链接还是显得那么有用。

其他部分

这是一些有可能包含在你的 README 文件中部分。

为什么需要这些

当你的项目借用了其他项目或者它的确很复杂时，在这里提供一些有用的帮助信息很是很有必要的。

常见问题

一些会被经常问到的问题

例子

获取示例应用程序运行时的示例代码或指针的链接

鸣谢

这部分是列出并感谢那些为这个项目做出非技术性贡献的人

更新日志

这里应该放置项目更新日志的链接

现在我们拥有一篇优秀的 README 文档了!我希望更多的人在书写文档说明时能够考虑什么才是使用者所需要的，如有遗漏，欢迎提出意见。

Linux Story 小编温馨提示，更多详情请访问如下原文链接。

原文链接：http://rowanmanning.com/posts/writing-a-friendly-readme/

译文链接：http://www.linuxstory.org/writing-a-friendly-readme/

转载请注明出处，否则必究相关责任。