如何书写项目README.md文档

背景

编写一个项目的 README 就像是写一本书的序言一样，一个好的项目不应该仅仅只有一份高质量代码，同时更应该有一份高质量的文档。而对使用者来说，一份好的文档能够节省大量的时间。

文档结构

基本选项

• 项目背景介绍
• 项目基本介绍
• 项目开发环境
• 项目启动或者使用说明（重要）
• 项目API参考（重要）
• 项目功能描述（重要）
• 项目结构简介（内部项目）
  • 项目一些配置文件说明
  • 项目重要代码文件说明
  • 项目敏感文件说明
• 测试DEMO
• 项目测试运行效果
• 作者列表
• 更新链接
• 历史版本
• 联系方式
• 开源协议

以上内容非必选项,根据项目需要书写即可

选项解析

项目背景介绍

• 简单介绍下项目编写的背景
• 项目编写的初衷之类的，项目创作的动机之类的（一般都是我们抒发情怀的地方）

项目基本介绍

• 也可以和项目背景介绍合在一起
• 解释下项目到底是什么，解决了什么问题
• 介绍项目为什么编写，解决了什么问题，未来可能会解决什么问题等

友情提示

类似网络小说中的开篇，一般都是解释三个问题：

我是谁？我在哪？我要干什么？

项目开发环境

• 介绍自己项目是在什么环境下开发的
• 虽然项目可能是通用环境都可以运行，但是推荐还是写一下
• 万一有人想要编译重写我们的项目，最起码有个指引不是

项目启动或者使用说明（重点）

• 我们拿到一个项目，一开始肯定是要知道项目怎么用
• 所以，我们的项目文档必须有详细的项目启动说明和使用说明
• 必须让用户可以根据说明，非常简单的使用我们的项目

项目功能描述（重点）

• 这里是我们的闪光点，展示我们项目的优势和功能，来吸引用户使用我们的项目
• 项目功能描述要详细，要做好功能分类，有条理的介绍下项目的功能
• 让用户可以非常简单的了解我们的项目，非常简单的找到他需要的功能，并且使用我们的项目

项目API参考（重点）

• 根据项目的大小，如果它足够小且足够简单，则可以将参考文档添加到README中。
• 对于中型到大型项目，至少提供API参考文档所在位置的链接非常重要
• 要让用户很简单的找到怎么参考API来使用和运行我们的项目

项目结构简介

• 一般这个是公司内部项目文档需要写的，因为如果新人接手项目，有一份目录介绍文档和一些逻辑和重要代码文档，可以帮助新人很快的熟悉和接手项目
• 如果项目有一些重要的配置文件（比如，数据库的配置，开发环境和线上环境的配置，一些报错配置，一些协议配置等），那么我们的项目文档肯定要针对这些文件做描述的
• 如果我们项目有一些重要的逻辑，和一些重要的修改，当开发人员觉得项目中的注释或者版本提交记录不足以描述很清楚的时候，可以在项目中添加这些代码的说明，这也是可以的

项目测试DEMO

• 一个项目测试Demo是必不可少的
• 只告诉用户怎么配置，不给用户Demo，万一用户按照我们的指导运行不成功怎么办
• 程序员喜欢用Demo说话，同时我们的用户也喜欢通过DEMO来了解我们的项目
• 这就要求我们在项目文档中提供项目demo下载地址或者项目demo的github等

项目测试运行效果

• 描述并展示如何使用代码示例运行测试
• 并且提供项目的测试结果

项目作者列表

• 如果是大型项目，贡献者肯定不止一个人，我们完全有必要或者是必须列举那些为项目做过贡献的人
• 这不仅仅对他们成绩的肯定，也是对于他们的一种尊重

项目更新链接

• 项目更新对于开发人员是一件很苦的事情，同事对于我们的用户也是一件痛苦的事情
• 如果新版本的项目修改了很多，那么我们必须针对每个更新提供有用的信息，供用户参考

项目历史版本

• 项目历史版本更新情况
• 项目每个版本的差异等都可以在这里提供链接
• 一些重要的更新修改，可以在这里重点指出来

还有最好是能有一份 CHANGELOG 文档，对不同版本做了哪些修改，有什么特性等等，让用户知道每个版本干了什么。
前端 CHANGELOG 生成指南

项目联系方式

• 告诉用户项目如果除了Bug或者其他问题，怎么与我们沟通交流

项目开源协议

• 给出项目的开源协议

参考资料

【前端进阶干货系列】前端规范化（四）README.md