如何写好一篇README

1. 前言

相信用过github的朋友都接触过GitHub项目的READEME，它是一种编辑文档，主要是用来介绍项目的一些情况，下面我们来学习一下。

2. 规范的README会有哪些内容

我们通过一张截图一起来看看一份简单的README规范都有哪些内容：

上面的readme规范模板在我们feflow的README规范里可以看到，那么我们一起来探讨下，一份规范完整的README规范都应该有哪些内容呢？

* 项目描述

* 如何运行

* 业务介绍

* 项目备注

每一项都有哪些作用？

项目描述

需要说明我们的项目名，项目功能简述，代码仓库地址，以及该项目的第一负责人。谁交接给我们的项目，谁就是该项目的第一负责人。

如何运行

开发环境配置：一般是我们需要的一些运行环境配置。

 

开发&发布：我们怎么通过命令开启本地开发，以及构建发布。

 

代理配置：如果我们的项目在本地开发时需要用到一些代理工具，例如fiddler或whistle等，我们需要列出代理的配置项。最好是直接导出一个代理配置的文件，放在项目下发布。如果我们有用到一些发布平台，最好贴上项目的发布模块和发布单，减少我们发布的时间成本。

 

错误告警及监控：相信我们平常都会对线上的项目部署错误告警和监控日志的服务，方便我们及时排查现网问题，这里我们可以加入项目的一些监控属性ID。

 

接口API：这里我们需要贴入项目中拉去的后台接口地址以及描述，还有我们的接口负责人，当后台服务异常，可以直接联系的方式。

 

数据上报：我们在平常项目里都有加入一些数据上报，给产品同学统计业务数据用，这里我们最好阐述下都有哪些数据的上报。

业务介绍

业务入口地址及渠道链接 即我们整个项目的入口页面，或者比较重要的页面地址。一般入口页面，我们可能会在多个渠道进行投放，那么需要列出所有的渠道链接，各页面及描述详细列出我们项目内的所有页面信息，比如下面这样：

 

页面目录	页面描述	页面链接	参数描述
index	首页	https://now.qq.com	无

项目备注

项目中需要告诉其他开发者一些关键信息，比如我们页面打包构建，需要注意哪些问题等等，这些信息虽然不是必须的，但是可以帮助其他开发者降低开发的风险成本。

3. README的书写规则

3-1标题

等级表示法，分为六个等级，显示的文本大小依次减小。不同等级之间是以井号 # 的个数来标识的。一级标题有一个 #，二级标题有两个# ，以此类推。

例如：

# 一级标题  

## 二级标题  

### 三级标题  

#### 四级标题  

##### 五级标题  

###### 六级标题

3-2字体强调

*强调*  (示例：斜体)  

 _强调_  (示例：斜体)  

**加重强调**  (示例：粗体)  

 __加重强调__ (示例：粗体)  

***特别强调*** (示例：粗斜体)  

___特别强调___  (示例：粗斜体)  

3-3代码显示

`<hello world>`  

4-4代码块高亮

 ` ` `

高亮内容

` ` `    

4-5文字引用(>)

> 第一行引用文字  

> 第二行引用文字  

4-6图片引用

图片:

  

链接:  

[链接名称](https://www.baidu.com/)   

4-7表格

表头  | 表头  | 表头

---- | ----- | ------  

单元格内容  | 单元格内容 | 单元格内容

单元格内容  | 单元格内容 | 单元格内容  

 

4-8列表

1. 项目1

2. 项目2

3. 项目3

   * 项目1 （一个*号会显示为一个黑点，注意：有空格，否则直接显示为*项目1）

   * 项目2  

 

4-9换行

注意：直接回车不能换行!!!
1、在上一行文本后面补两个空格，这样下一行的文本就换行了。
2、在两行文本之间加一个空行。也能实现换行效果，不过这个行间距有点大。