聊一聊 - 如何写好README文档

---

前言

前面的《聊一聊 - 如何像开源项目一样，去设计一个组件》我们提到了组件设计的一些思路和注意事项。

本文的话我们一起聊一下为什么要去写README以及如何去写好一个组件的REAME，这里很多是我的一些个人经验可能对于初学者会有一些帮助和启发，如果大家有更好的理解和思考也可以评论一起讨论下。

1. 为什么要写好README

在思考为什么要写README之前，大家先想一下现在我们收到了一任务要合并一个组件，然后有个人给了你一套源码，说你合并吧，此时你心里是不是会产生如下疑问

• 这是个啥组件啊
• 这个组件怎么接啊
• 这个组件的软件设计是啥样的啊？
• 接入这个组件需要消耗多少资源啊
• 这个组件有没有啥坑需要我注意的啊
• 这个组件到底TMD是个啥啊，我怎么评估工作量啊

然后当你好不容易接入之后，后续要进行维护又会碰到新的问题

• 这个组件最近有没有更新啊
• 这个组件上我碰到了个问题A，然后我花费了好几天修复好了，最后发现组件很早前自己就修复了
• 我需不需要更新组件啊
• 组件有没有增加什么新功能啊
• 我去哪里查看组件改了啥啊，代码又去那里合并啊

相信上面问题大家在工作中多多少少都碰到过，别问我为啥知道（全程踩过坑出来的）。经历过这些之后大家也就明白了为啥招聘的时候会要求有一定的文档撰写能力，并且最好文档写的好一些。因为好的文档真的能够很大的提高团队合作的效率。

我一直觉得我们不能自己骂娘，然后又干着让别人骂娘的事，这样的话就会形成一个负循环，所以从我们自身开始就要养成去写文档以及写好文档的习惯。

2. 如何写好README

聊完了为什么要写README后，大家估计多少有点感同身受了，那么接下来我们去讨论下如何去写好一个README(个人经验总结，不属于什么权威之类的啊，大家也可以按照自己的理解去尝试写自己风格的README)。

2.1 文档是离线还是在线

我个人觉得文档最好是离线的也放一份，在线的也放一份。那么此时离线和在线所要表达的内容就不一样了。
离线文档
离线文档一般和代码放在一起，用户能够随时看到但不保证是最新的。所以这里最好就是放一些简单的不长变化的内容。让读者能知道这个组件是个啥，有个大概的了解

然后最重要的，要放一个在线文档的地址，这样读者才能知道在线文档在哪里

2.2 用什么格式

这里推荐使用markdown，编译起来更加容易。同时格式就是utf-8的，修改了文档之后，我们比对文档改了啥时就像比对代码一样，一眼就能看出来改了啥，如果使用的是word比对的时候可能是一段乱码，想一想我们用文本打开word格式的内容是不是乱码。

而且现在很多AI工具对markdown的支持更好，后续想要修改格式例如转换成网页和pdf或者ppt之类的也更加方便。

2.3 写那些内容

1. 简介

写简介的目的很简单，就是告诉别人

• 这个组件是个啥。
• 为什么会有这个组件
• 以及组件相关的重要链接等在哪里（例如在线文档的链接）
• 还有这篇文档说的是个啥

2. 软件框架介绍

写软件框架介绍的目的是告诉别人

• 软件是怎么进行设计的
• 软件整体风格是什么样的
• 软件的工作目录是怎么样的
  
  

这样做的目的是让使用组件的人能够更快的适应我们的设计思路和代码风格，这样接入时即使文档写的不全面，接入者也能根据自己的思考去更快的接入。

同时告知到对放整体风格是什么样的能够让其他人在修复组件上的问题时，统一编码风格，方便我们将其合入到主线

3. 如何进行移植

现在别人已经知道了我们的组件是什么，同时对软件设计和实现也有了一个初步的了解。接下来就该告诉他们怎么去用了。

在写这部分文档之前，我们最好自己写一个移植的demo，毕竟是编码，很多时候代码就说明了很多的东西了。

所以当有了demo之后，我们没有必要写的非常详细，更多的是要强调重点。例如之前我在写如何移植时，分成了以下部分

4. 注意点

现在别人知道怎么移植了，也相当于把我们的组件用起来了，此时我们就要围绕使用过程中的一些注意点来给使用者一些提示了。

这部分可以来自于自己移植过程中碰到的需要注意的点，以及容易出错和被误解的地方。
主要是避免使用者踩坑。
例如：

5. 问题解答FAQ

这部分是助人为乐也让自己解脱。为啥呢，我们想想当用的人多了多多少少都会有些问题过来问。
A有这个疑问，代表着B可能也有这个疑问。如果我们每个都回复一遍，那也太影响我们的工作效率了。

所以我们需要把别人问到的问题给整合起来，然后形成文档记录，这样有问题了先让他看文档，文档中没有的话我们再去回答，然后再把这部分新的回答整理成文档，后续这个FAQ会越来越完善。

例如：

6. TODO(已完成+待办)

ToDo主要是记录自己当下做了啥，哪些还没做。有了ToDo的话，使用者就能够知道我们大的进度上有了哪些改变，同时记录还有哪些东西没做也是对组件的未来规划做个记录。防止我们忘记了。
（我说的一切都是站在如何把组件做的更好的角度上去思考的啊，虽然我也知道有时候你写了自己没做啥，领导会一直记着你没做啥天天催你哈哈哈）

7. 实现修改记录

现在组件被很多人使用了，但是并不代表我们的组件就开发完成了，我们仍然需要不断地去新增、优化以及解决组件的问题。

那么使用组件的人怎么知道当前组件更新了哪些内容以及应该去到哪里去同步呢？这个时候实现修改记录就非常重要了。我们可以通过记录下修改点的日期+修改内容+路径来告知到别人做了哪些修改，什么时候修改的，应该去哪里同步。

例如

3. 总结

写好README实际上并没有说最标准的答案，最本质上的思路是把自己所负责的组件当作一个产品去看待，把使用组件的人当作用户去看待，通过文档甚至视频等方式，去向他们宣传我们的组件，让他们都能用我们的组件以及觉得这个组件好用。

然后文档很难一下子就写的非常面面俱到，更多的是后续维护过程中不断的进行优化和补充。所以刚开始不要有心里负担，慢慢的一点点来，时间长了积累起来的内容就是一股不可小觑的力量。