制作公司的网站,建立门户网站的程序,wordpress域名地址设置,全屋设计效果图文章目录 前言1. 为什么要写好README2. 如何写好README2.1 文档是离线还是在线2.2 用什么格式2.3 写那些内容1. 简介2. 软件框架介绍3. 如何进行移植4. 注意点5. 问题解答FAQ6. TODO(已完成待办)7. 实现修改记录 3. 总结 前言
前面的《聊一聊 - 如何像开源项目一样#xff0c… 文章目录 前言1. 为什么要写好README2. 如何写好README2.1 文档是离线还是在线2.2 用什么格式2.3 写那些内容1. 简介2. 软件框架介绍3. 如何进行移植4. 注意点5. 问题解答FAQ6. TODO(已完成待办)7. 实现修改记录 3. 总结 前言
前面的《聊一聊 - 如何像开源项目一样去设计一个组件》我们提到了组件设计的一些思路和注意事项。
本文的话我们一起聊一下为什么要去写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实际上并没有说最标准的答案最本质上的思路是把自己所负责的组件当作一个产品去看待把使用组件的人当作用户去看待通过文档甚至视频等方式去向他们宣传我们的组件让他们都能用我们的组件以及觉得这个组件好用。
然后文档很难一下子就写的非常面面俱到更多的是后续维护过程中不断的进行优化和补充。所以刚开始不要有心里负担慢慢的一点点来时间长了积累起来的内容就是一股不可小觑的力量。
