读书笔记 - 活文档

中国有句俗语，好记性不如烂笔头，现代世界纸笔已经无需烂笔头了，但是一样的道理，人的大脑会遗忘很多东西，需要用文档来记录和分享有价值或重要的知识。

Gojko Adzic 的 “实例化需求：团队如何交付正确的软件” 一书中描述了执行 BDD（行为驱动开发） 的团队编写的需求说明和测试用例非常有用。
由于测试自动化，只要测试全部通过，这个文档就会始终保持最新。这种文档就是活文档。

在图书馆看到一本书 活文档 与代码共同演进，作者是法国人西里尔·马特雷尔（Cyrille Martraire）。
英文书名 - "Living Documentation: Continuous Knowledge Sharing by Design". 随手翻了翻, 记录一些要点

关于文档的问题

1. 为什么我们需要这个文档？
2. 真的现在就需要这个文档？
3. 可以通过对话或分享知识来替代文档吗
4. 文档要承载的知识现在在哪里？人脑中，代码中，散落在 wiki 或日志中
5. 这些知识的稳定性如何？是不是时常会修改和更新

活文档有以下四个原则

• 可靠： 无论何时，活文档都是准确的，并且与所交付的软件保持同步
• 省力：活文档最大限度地减少了文档工作量，即使是软件发生了变更，删减或添加，活文档只需极少的额外工作，而且只需要操作一次
• 协作：活文档可以促进所有参与者之间的对话和知识共享
• 有见地：活文档会将人们的注意力引导到工作的各个方面，从而提供反馈机会并鼓励深入思考，它能帮助你反思正在进行的工作并做好更好的决策

持久性文档有两种形式：外部文档(readme, wiki, word 及 ppt)和固有文档（注解，注释，测试用例及配置文件）。存储文档的最佳位置是被记录的事物本身。

有一点令人印象深刻，与我日常的做法不谋而合，文档应该尽量自动化生成，写文档不仅要让人容易阅读，还要让机器容易阅读。

“活文档”一书中整理了近百种模式，分为13个大类

总体来说，这本书值得一读，只是篇幅挺长，很难一次性读完，值得放在手边慢慢读。

学习知识，管理知识，吸收和运用知识是每一个知识工作者所必须掌握的技能，活文档是很好的思想和方法。