编写README文档（Markdown）

首先需要注意的是，没有官方规定 readme 应该怎样去写，不需要将 readme 保持在同一长度。视具体情况，可以写得很长也可以很短，这取决于具体的项目。重要的是清晰准确地向用户传递必要信息，并避免默认读者已具备相关知识。

readme 要以精简的方式想用户传递信息，帮助他们配置并运行程序，要牢记我们是在为其他人而写。

1. README 剖析

开始是标题和说明，一两句话就好----要确保清晰准确地表达项目精神。如果想做的更精致些，可以把项目 Logo 放进去。

下面继续补充理解代码所必须的信息----比如对其他软件的以来、安装说明、通常用法、已知 BUG。

通常开发者会准备一个 getting started 或者 installation 部分，以在初始配置方面提供帮助，必要时引入事例代码，展示代码的正确用法。

2. 用 Markdown 便携易读的 README 文档

Markdown 能帮助建立良好的排版，自动转化为 HTML 进行显示。开发者们聚集的网站，如 GitHub，Stack，Overflow 甚至 Reddit 都支持 Markdown 语法实现快速方便的内容排版。Markdown 写 readme 的最大优势是排版后的文字非常适于快速阅读。

2.1 Markdown 基础知识

Markdown 是一种轻型标记语言，经常用于 README 的编写。它非常简单，大部分语法都很直观。

但实际上，Markdown 有许多不同的“方言”，就像在口语中一样。其中每种“方言”都被称为 Markdown 的“风格（flavor）”。这些方言大部分都大致相同，只有细微差别。

由于我是要用于 GitHub 上，因此这里使用的是 GitHub 风格的 Markdown。

2.1.1 设置文本加粗

要将文本设置为粗体，请用两个星号将其括起。因此，这行代码：

Isn’t today a **wonderful** day?

会显示为：Isn’t today a wonderful day?

2.1.2 设置文本斜体

要将文本设置为_斜体_，请在文本两旁添加下划线。因此，这行代码：

And in that moment I thought to myself: _Did I turn off the stove?_

会显示为：And in that moment I thought to myself: Did I turn off the stove?
与上一个示例相似，这样的代码更接近自然语言，原始文档浏览起来非常方便。

2.1.3 码，还是 不码?

内联代码标记，用于标注普通文本中的代码，为此，需要在代码文本两旁添加反撇号（`，不是单引号）。因此，这行代码：

You should use the `strong` tag.

会显示为：You should use the strong tag。这比直接显示 “You should use the strong tag.” 有意义多了。

2.1.4 标题顺序

标题更简单，对于 h1 到 h6 标签，只需要在文本前添加 #。Markdown 会根据 # 的数量生成响应的标题标记。例如：

## This is an h2.

## This is an h3.