如何写好 README

引言：因为 README，6 个月后的你仍然知道当初写了什么；因为 README，其他人看一眼就能知道是否需要；因为 README，让你的代码更有质量；因为 README，你成了个作家。

README是documentation的一种。

Documentation

documentation的潜在用户 包括：

你自己，有可能半年后你看自己的代码，不晓得当时脑子在想啥？

你同事， 毫无疑问，你也会看到团队里其他人的代码。

你写的library的用户，写的library当然是想给别人用啊。

如果不写documentation的话，其他的engineer团队极有可能不使用你的library, 或者转而使用better-documented的library,  或者，如果你的library很重要，其他团队就需要自己写文档，相当于增加了他们的工作量。

README

README 是一种说明文件，通常随着一个软件而发布，里面记载有软件的描述或注意事项。这种档案通常是一个纯文字文件，被命名README.TXT、README.1ST或http://READ.ME等等；但也有RTF或DOC格式的读我档案。它的档名通常是以大写英文来命名的，因为大写英文字母比小写有着较小的ASCII码；亦因此在一些以ASCII排序档案的环境里，它能被保证被列在档案列表的第一位。这种档案的特殊命名使任何人能第一时间发现并阅读这个档案，即使他们本身并没有关于 README 的相关知识。

README 应该要简短，并且能够节省时间。

重点是：提供足够的context 让你的user可以get your library up and running. 我们需要对用户nice, 要知道作为程序员，你已经对你的代码很熟悉了，但是你的用户对你的代码一无所知，所以要把他们需要了解的点点滴滴在readme里指出来。

- Communicate clearly and concisely any information that is essential for the user 

- Don't make assumptions about what the end user already knows

完整的 README 应该包括以下：

• 项目和所有子模块和库的名称（对于新用户，有时不同命名会导致混乱）
• 对所有项目，和所有子模块和库的描述

• 如何使用 5-line code（如果是一个库）

• 版权和许可信息（或阅读许可证）

• 抓取文档指令

• 安装、配置和运行程序的指导

• 抓取最新代码和构建它们的说明（或快速概述和「阅读 Install」）

• 作者列表或「Read AUTHORS」

• 提交bug，功能要求，提交补丁，加入邮件列表，得到通知，或加入用户或开发开发区群的介绍

• 其他联系信息（电子邮件地址，网站，公司名称，地址等）

• 一个简短的历史记录（更改，替换或者其他）

• 法律声明

Apache HTTP Server 的 README 和 GNU 的README 都很简洁清晰。

举个例子：

• 如果用英文写的文档，只用 ASCII
• 如果可能写不同语言，比如README.ja
• 每行少于 80 个字符
• 段落之间空行
• 标题下划线
• 使用空格而不是 tab 锁紧

把以上结合起来就成了：

Documentation
-------------

GNU make is fully documented in the GNU Make manual, which is contained
in this distribution as the file make.texinfo.  You can also find
on-line and preformatted (PostScript and DVI) versions at the FSF's web
site.  There is information there about ordering hardcopy documentation.

  http://www.gnu.org/
  http://www.gnu.org/doc/doc.html
  http://www.gnu.org/manual/manual.html 

另外一个例子如下：

Title

Description

Installation

How to install your library

Usage

How to use your code

Known bugs

Any known defects

Licenses

The license information

这里贴上wiki对README的定义：

A readme (or read me) file contains information about other files in a directory or archive and is very commonly distributed with computer software.

and it lists the following contents:

• configuration instructions
• installation instructions
• operating instructions
• a file manifest
• copyright and licensing information
• contact information for the distributor or programmer
• known bugs
• troubleshooting
• credits and acknowledgements
• a changelog