中国有句俗语,好记性不如烂笔头,现代世界纸笔已经无需烂笔头了,但是一样的道理,人的大脑会遗忘很多东西,需要用文档来记录和分享有价值或重要的知识。
Gojko Adzic 的 “实例化需求:团队如何交付正确的软件” 一书中描述了执行 BDD(行为驱动开发) 的团队编写的需求说明和测试用例非常有用。
由于测试自动化,只要测试全部通过,这个文档就会始终保持最新。这种文档就是活文档。
在图书馆看到一本书 活文档 与代码共同演进,作者是法国人西里尔·马特雷尔(Cyrille Martraire)。
英文书名 - "Living Documentation: Continuous Knowledge Sharing by Design". 随手翻了翻, 记录一些要点
![](https://i-blog.csdnimg.cn/blog_migrate/ac5dc1dd0377ea76709db4ad12056674.png)
关于文档的问题
- 为什么我们需要这个文档?
- 真的现在就需要这个文档?
- 可以通过对话或分享知识来替代文档吗
- 文档要承载的知识现在在哪里?人脑中,代码中,散落在 wiki 或日志中
- 这些知识的稳定性如何?是不是时常会修改和更新
活文档有以下四个原则
- 可靠: 无论何时,活文档都是准确的,并且与所交付的软件保持同步
- 省力:活文档最大限度地减少了文档工作量,即使是软件发生了变更,删减或添加,活文档只需极少的额外工作,而且只需要操作一次
- 协作:活文档可以促进所有参与者之间的对话和知识共享
- 有见地:活文档会将人们的注意力引导到工作的各个方面,从而提供反馈机会并鼓励深入思考,它能帮助你反思正在进行的工作并做好更好的决策
持久性文档有两种形式:外部文档(readme, wiki, word 及 ppt)和固有文档(注解,注释,测试用例及配置文件)。存储文档的最佳位置是被记录的事物本身。
有一点令人印象深刻,与我日常的做法不谋而合,文档应该尽量自动化生成,写文档不仅要让人容易阅读,还要让机器容易阅读。
“活文档”一书中整理了近百种模式,分为13个大类
![](https://i-blog.csdnimg.cn/blog_migrate/d604d440e0b50a34f1814e0022882204.png)
总体来说,这本书值得一读,只是篇幅挺长,很难一次性读完,值得放在手边慢慢读。
学习知识,管理知识,吸收和运用知识是每一个知识工作者所必须掌握的技能,活文档是很好的思想和方法。