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/