1. 前言 最近想用博客来记录一下自己的学习过程，以前都是用有道云记笔记，每次查看笔记都需要登录，而且笔记仅自己可...
什么是git版本管理控制工具（vcs） 1.分布式版本控制 2.多个开发人员协调工作 3.有效监听谁做的修改 4....
早起打卡 晨间日记 日程安排 阅读分享 课程笔记+作业 睡前复盘 理财
这段时间因为执迷简书上的文字，每日一早五点半我就会自然的苏醒。 这连日来的几天里，我中断了坚持一个多月的日更，没有...
Python部落()组织翻译，禁止转载，欢迎转发。
说明文档“README”这个词是哪来的？
这个术语至少出现在70年代以前，在PDP-10这个文档里可以看到。这个词的起源甚至可以追溯到人们在一堆纸质文档的最上方摆上一份带有说明信息的文档，上面涂写着大大的“READ ME”字样，用于描述下面文件的用途。
一位读者说README这个说法在调侃爱丽丝漫游仙境，在小说中有一瓶药剂和一块蛋糕，分别写着“喝我”和“吃我”。
一直以来README的习惯写法都是全部字母大写。除了大写字母比较醒目的原因以外，UNIX系统会把大写的文档名排在其他小写文档的前面，这样README作为指导性文档就可以很清晰地出现在最顶端。
这样的意图很明白：“在用户进行操作之前请阅读这份重要文档”。那我们一起看看现在这些“重要文档”都包含什么信息吧。
面向创建者，面向使用者
这篇文章会介绍各种README。讲它们做什么，为什么它们必不可少，以及如何优雅地创建它们。
本文面向模块的创建者。作为模块的创建人，你要专注于做长期可用的东西。这是一项自我要求，即便作者不考虑把作品开源。半年过后，如果你的模块没有被良好记录，那么它会变得陌生。
这篇文章也适合模块的使用者。每一个模块的创建者也是模块的使用者。Node有一个非常好的相互依存度：没有什么是处在依存性的最底端的。
琳琅满目的模块：良莠不齐
Node系统因为各种模块而更加强大。npm是让所有奇妙事情发生的魔法。在一周的时间内，Node开发者可以评估数十个模块，并将优秀的模块放入他们的项目里。每天都有很多新能量迸发出来，新的成果可以被采用，只要你输入npm install，它们都唾手可得。
如同其他非常友好的生态平台一样，内容质量良莠不齐。npm尽最大努力去把它们打包并传播到世界各地。然而，打包的各个模块相去甚远：有的金光闪闪并更新及时，有的破破烂烂令人恼火，剩余的质量介于这两者之间。甚至有一些模块我们根本不知道它们能做什么！
模块的缺点各种各样：命名不准确或没有意义（猜猜fudge模块能做什么？）；没有写文档记录；没有测试；源代码没有注释；功能名称难以理解。
许多模块没有日常的维护人员。如果一个模块没有人可以提供咨询或者解释这个模块的功能，再加上没有留下文档记录，它就像一个外星人留下的神器，对于未来的考古黑客来说难以理解或使用。
缺乏文档记录的模块处于质量分级的哪个档次呢？可能只需要加这么一行说明：“给数字根据16进制排序”，或者加一段示例代码。这都比什么都没有好得多，但可能造成对于现在模块发掘者来说最坏的情形：深入源代码去尝试并弄明白它究竟是怎么工作的。写明晰的文档最终目的是提供足够的指导让使用者远离源代码，充分利用你模块提供的抽象层。
Node有一个非常“宽”的生态平台：它是由一系列相互独立并专精于做某一件事的模块组成的。有个别例外，但除去这些封地外，Node世界的广大领土是被各种单一目标的寻常模块以数量优势占领的。
自然而然，你会发现寻找满足你需求的模块非常困难。
这可以忍受。没错。一个低门槛且有检索困难的平台比起倾向于少数几个开发者的生态恶劣的平台好上无数倍。
而且，检索问题——正如它表现出的一样——比起其他问题更容易解决一些。
条条大路通，一个替代npm搜索的方案，根据你Github圈子里其他朋友喜欢或者使用的模块为你推荐模块。
当然也有npm的内建搜索功能：一个安全的默认选项，是新手开发者的常用渠道。
不管你用哪种方法把模块发出去，也不管这些模块发掘者最终在或者其他的地方找到它，他们所做的第一件事都是阅读README。既然你的用户无一例外地都会做这件事，那我们如何能留下最好、最有效的印象呢？
README文档是模块使用者第一个——也可能是唯一一个——看你作品的渠道。使用者希望你的模块能满足他们的需求。所以你必须讲明白你的模块满足何种需求，以及能达到怎样的效率。
1，告诉他们这是什么（包括背景介绍）
2，向他们展示实际使用的样子
4，告知其他可能相关的细节
这是你的责任。模块能否成为一堆平庸模块里闪闪发光的宝石完全取决于作者。鉴于许多开发者会在看别的内容前先阅读README，该文档的质量成为大众衡量你作品的指标。
缺少README文档是很明显的缺陷，但长篇大论的README并不等同于高质量。最理想的README文档应该精简到极致。事无巨细的记录是好的，给它们单开一页，保持README文档的简洁！
有言道，不从过去吸取教训的人将会犯同样的错误。开发者写说明文档已经有一些年头了。如果你不回头看看在Node之前其他人写了什么，那对于你是一种浪费。
Perl，就它所拥有的各种附加组件而言，某些程度上类似Node的爷爷。两者都是高级脚本语言，采用了许多UNIX的习惯语句，通过网络加速发展，并代表着各自的庞大生态圈。
因此我们发现Perl monks的人对于写优秀的README文档有丰富的经验。CPAN是一个非常棒的资源，值得你去学习一个社区如何保证文档处于较高水准。
没有README？那就没有抽象层
没有README意味着开发者需要深入你的代码去理解它。
Perl monks对于这个问题有独到的见地：
如果别人可以在阅读文档后直接使用你的模块而不需要查看代码，你的文档才算完成。这非常重要。这把你的模块的交互界面同它的内部构造拆分开来。这样做的好处是你可以改变模块的内部而无须再对交互界面进行改变。
请记住：文档，而非代码，定义一个模块的功能。——Ken Williams
一旦找到README文档，勇敢的模块探索者就会浏览它，辨别模块是否能满足自己的需求。对于他们的大脑最终变为一系列特征比对的任务，每一个步骤都把他们带到模块细节的更深处。
让我们举个例子，我要找2D碰撞检测模块，于是找到了collide-2d-aabb-aabb。我从头开始研究它：
1，文件名——一目了然的名字是最好的。collide-2d-aabb-aabb看起来符合这个特征，虽然它假设我知道"aabb"代表什么意思。如果文件名看起来太虚或者不相关，可能就需要改善一下。
2，一句话描述——配有一句稍带细节的话描述模块是什么，可以帮助使用者知道模块具体可以做些什么事情。collide-2d-aabb-aabb写它：
判定一个轴对齐的带框盒子（缩写为AABB）是否和其他AABB发生碰撞。
太棒了：这句话给出了AABB的定义，以及模块的功能。现在我们更深入地了解它如何用在我的代码里：
3，用法——在深入阅读API文档之前，我们可以先看看模块实际运行起来是什么样的。我可以很容易地判断JS例子是否是我想要的形式并能解决我的问题。大家对于promises/callbacks等异步处理和ES6等都有不同的要求。如果它符合我的要求，那么我可以更深入地了解它。
4，API——这个模块的名称、描述、用法都非常吸引我。我现在已经非常倾向于使用它了。我现在只需要浏览一遍API以确保模块能完成我所需要它做的事情，并且能很容易地整合到我的代码里。类型如果不是显而易见的那么也需要考虑进来。还要弄明白注意事项。
5，安装——如果我做了上述几个步骤并到了这里，那么我肯定会使用这个模块。如果模块的安装是非标准化的，那么应该写在这个部分。但即使是常规的npm install，我也会在这里写明。Node随时都有新用户，所以一个/defstream/nl3
