现代前端库开发指南系列（三）：从说明文档看库的前世今生

前言

我们在工作中很多时候都要做技术选型，去找寻既能满足自己需求又靠谱的第三方库；在前端开源生态季度繁盛的现状下，只要不是太小众的需求，我们很容易就能找到一堆相关的开源库，那我们具体要怎么做决策呢？我的做法是，先阅读开源库的说明文档让自己有一个感性的认识，然后挑选出其中的两三个库来进行更深入更全面的了解。如此说来，这说明文档是不是就很像我们求职时的简历呢？“简历”关都过不了，何谈“offer”啊！

本文将介绍一个库（即不局限于前端领域）所要具备的说明文档，主要包括 README.md、CHANGELOG.md、LICENSE，这些说明文档均需放置于项目的根目录。

README.md

当我们进入 GitHub 中的某一个开源代码仓库页面，除了项目信息、代码目录结构外，最先映入眼帘的就是 README.md 了，可见，其重要性不亚于 index.html 之于一个网站。

README.md 需要满足以下这些要求：

• 准确（包括字母大小写）命名为README.md
• 符合 markdown 语法
• 每个章节都应有标题
• 中、英文连接处应有空格分隔
• 使用 markdown 语法包裹代码片段，并注意标注代码段的语言种类，如：

console.log('code in javascript');

必须包含的内容

一份优秀的 README.md 需要包含以下内容：

• 名称：必须与库的名称保持一致。
• 简介：以 markdown 语法>开头；尽量保持简洁且字数应少于120；与 GitHub 仓库（如果有的话）和 npm 包（同样是如果有的话）的描述保持一致。
• 库的安装方法：如何安装本库，在前端领域下通常指如何安装 npm 包或用