为什么要写README文档

说起README文档大家再熟悉不过了，在Github打开一个项目，项目源码下面默认就会展示一个README文档。那么为什么要有这个文档呢？

说简单了，就相当于你项目的一个说明书。它告诉了你，为什么要使用它，以及如何获取和如何使用等等信息。如果你的文档是完整的，那么使用你代码的人就不用再去看代码了。这样可以分离接口文档与具体实现，意味着你可修改实现的代码而保持接口与文档不变。

如果想把所有信息都清晰准确的表达出来并不是一件容易的事儿，那么制定一些README文档的规范是势在必行的，接下来介绍一下如何去写好一个README文档。

如何编写README文档

对于README文档，大致分为几个部分：

• 背景
• 安装
• 示例 或 用法
• 维护者
• 使用许可

Banner

这里的banner就像网站的Banner差不多，展示一下项目Logo也好，大致预览图也好，就是个粗略的预览效果，还可以添加写徽章。我们拿Ant Design举例:

我们知道Github是全世界开发者的代码托管平台，如果有能力也可以在这里做一个国际化语言选择的选项。

目录

目录就相当于这个README文档的段落索引，一般在文章开头的位置，如果文档很长，不至于用户每次都需要一点点向下滚动，直接点击目录标题就会跳转到索引的标题位置，说白了就是前端所说的锚点跳转。如果文档内容并不多，也可以不用写。

例如我们看一下Axios的文档目录：

背景

这部分主要介绍一下为什么要开发这个项目，主要解决了什么问题，大致的使用场景和使用的技术栈，让使用者可以很快的了解这个项目是否是自己感兴趣的，如果官网最好贴出官网详细介绍的链接，毕竟篇幅有限。

安装

安装部分要说清楚安装需要的环境配置，最好简单给出环境配置的方式。接下来就需要说明如何安装，通过哪些命令安装，安装时需要注意哪些事情。我们看一下下面Express包的README文档是如何写的：

示例 或 用法

示例是指你得包或者工具也好，在实际安装后如何去使用它，要强调说明一下，使用说明并不是说要你长篇大论所有的使用方法，而是简单给出一个使用的Demo就好，如果需要详细的使用说明，可以制定一个文档地址去预览。README的重要功能就是言简意赅，让使用者一目了然。

接下来拿React-Dom的文档举例：

使用过React的同学都知道，React库的使用方法很多，这里只是简单指明了两种使用环境或者场景下一个简单的Demo，如果使用很简单，也可以加上API标题，介绍一些具体的使用API.

维护者和协作者

致力于一个项目并促进该项目发展的用户。通常所有者和维护者是同一个用户或组织，他们对项目库都有写的权限。

贡献者

每一个对该项目发出过pull request并合并到项目中的用户都是贡献者。

使用许可

一个LICENSE文件当然就是该项目的许可证了。一个开源项目的license会告诉用户他们能做和不能做的（例如使用、修改、重新发布），及告诉贡献者他们允许其他人做的。有许多的办法对开源项目加上许可证，你可以在choosealicense.com读到更多的关于每个许可证的含义。

总结

简单做一下总结，首先我们介绍了为什么要写README文档，简单说就是让别人能够快速快速的了解这个项目具体是什么以及如何使用。

接下来介绍了一下我平时写README文档时用到的一些模块，其实这些并不是有且仅有这些模块，我们当然也可以自定义一些更有意义的模块，本篇文章只是提供一些常用的信息，供大家参考。

最后补充一句，README文档的目的并不需要有多高的逼格，多绚丽的页面，最最重要的是把东西讲清楚就好，使用者并不是来你这看一些好看的图标，只是想快速的了解信息。