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