如何写好README

这个是UDACITY的免费的公开课。授课人是一线的工程师。相比于coursera，更接地气，能说出engineer的痛点。下面是听课的笔记。

README是documentation的一种。

---

Documentation

documentation的潜在用户 包括：

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

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

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

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

---

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

一个例子如下：

Title

Description

Installation

How to install your library

Usage

How to use your code

Known bugs

Any known defects

Licenses

The license information

---

Markdown

http://www.markdowntutorial.com