文档的反模式

May 21, 2023 by walter

在一般人眼里, 文档是个很无聊的东西, 写了很多无用的东西, 在产品线上用不着.
最要命的是, 它的目的是帮助理解, 可是经常会由于没有及时更新而误导读者.

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

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

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

文档的反模式

1. 独立的活动
   文档与编码, 测试及部署之间没有紧密结合在一起

2. 需要手工转录

3. 冗余的知识
   如果所有的知识都能在代码中找到, 那么文档又有什么用呢?

4. 无聊的时间陷阱
   写文档会花费很多时间, 而花的时间与人与己往往并不划算

5. 脑转储
   只是将脑中所想的东西写下来, 没有组织和提炼, 想到什么就写什么, 读起来用处不大且费劲

6. 优美的图表
   一图胜千言, 问题在于图表要有引人注目的说服力和生命力

7. 迷恋符号
   UML 及专有符号的滥用, 让人陷入到细节中

8. 不用符号
   不用 UML 和专有符号, 如何能清楚的描绘数据流, 时序和代码结构

9. 信息墓地
   文档不是只写一次的东西, 需要常用常更新

10. 误导性的帮助
    文档最要命的是提供了错误的信息

11. 总有更重要的事
    维护高质量的文档很花间和精力, 当时间紧, 任务重的时候文档常会草草完成

Comments |0|