程序员最烦写文档

转载

mb6066e53e0c12a 2021-05-19 16:30:37

文章标签 Linux 文章分类 运维

据说程序员最烦写文档，第二烦其他人没写文档。

当你听到文档这个词会想到什么？

它很无聊。
要写很多字。
意味着你要试着使用 Microsoft Word，还不能忘了在哪里插入图片。
作为开发人员，我喜欢那些展现动作和行为的动态可执行文件。对我而言，文档是静止的，它就像一株枯草，了无生趣。
本来以为它能帮上忙，结果总是耽误事儿......
写文档很无聊，我宁愿写代码也不愿意编写文档！

程序员最烦写文档_Linux 我还是写代码去吧......

编写和维护文档需要大量时间。文档很快就会过时，通常不完整，编写文档和阅读文档的过程令人沮丧......是的，程序员眼里的文档就是这样，而且大家还能“如数家珍”地列出文档的十大缺陷。

传统文档的缺陷

就像劣质酒的香味会快速消失一样，纸质文档的内容也会迅速失效，令你头痛不已。

——@gojkoadzic

传统文档存在许多缺陷和几种常见的反模式。几乎每个程序员的项目中都有以下列出的这样或者那样的问题。

1. 自扫门前雪

即便是在声称“敏捷”的软件开发项目中，决定构建内容、编码、测试和准备文档这几项工作之间也常常是相互独立的。

程序员最烦写文档_Linux_02

自扫门前雪

活动之间相互独立会浪费大量时间并错失一些好机会。基本上，所有的活动都会用到相同的知识，只是以不同的形式和工件来使用，并且可能伴有一定程度的重复。另外，在流程中，这些“相同”的知识可能会演进发展，从而导致不同活动中的知识内容不一致。

2. 为文档再写一份文档

需要编写文档时，团队成员会选择一些已完成工作的知识要素，然后手动将它们转化成适合目标受众的格式。基本上，这是一个为代码里已经写好的文档再写一份文档的过程，就像古登堡发明印刷机之前的抄写员一样。

程序员最烦写文档_Linux_03

为代码里已经写好的文档再写一份文档

3. 文档很快就会过时

以上描述的“抄写”过程导致了知识的重复：最终，你获得了反映真实情况的原始知识来源（通常是代码）和一堆以各种形式复制成的知识副本。不幸的是，当一个工件（例如代码）发生变化时，你很难记得要更新其他文档。于是，文档内容很快就过时了，留给你的是一份无法信任的不完整文档。这样的文档有什么用呢？

4. 无聊的时间陷阱

管理层想为用户提供文档，还想用文档来解决团队中人员流动引发的问题。然而，开发人员讨厌编写文档。与写代码或使任务自动化相比，写文档一点意思也没有。对于开发人员来说，他们不太有兴趣编写一些会迅速过时且无法执行的无效文本。当开发人员需要写文档时，他们宁愿去处理真正在工作的软件。矛盾的是，当他们想复用第三方软件时，一般希望能有更多有用的文档。

技术文档工程师喜欢写文档，而且以此为生。但是，他们通常需要开发人员的协助才能获得编写文档所需的技术知识，而且经常做的仍是“手抄”知识。这个过程令人沮丧，也浪费了大量宝贵的时间。

掉进编写文档的“时间陷阱”

5. 想到什么写什么

因为编写文档不是一件有趣的事，而且我们只是因为必须要有文档才会这么做，所以编写文档时一般比较随意，不会考虑太多。结果是作者在编写文档时就做了“脑转储”，即想到什么就写什么。问题在于，这种随机的脑转储对任何人都无益。

想到什么写什么，文档不一定有用

6. 优美的图表

对于那些喜欢使用CASE（Computer-Assisted Software Engineering，计算机辅助软件工程）工具的人来说，这种反模式很常见。这些工具并不是为制作草图设计的。相反，它们鼓励使用各种布局和根据建模参考的验证来创建优美的大型图表。整个过程需要很长时间。即使这些工具能神奇地自动完成布局，创建一个简单的图表仍然需要很长时间。

7. 迷恋符号

我们发现 UML 符号现在越来越不受欢迎了。UML 在 1997 年被采用为标准，并在之后的十年里成为所有软件的通用符号，尽管它并不适用于所有情况。从那时起，再也没有其他符号被广泛地使用，而且即使不太合适，世界各地的团队仍会用一些UML符号来记录内容。当你只知道 UML 时，每一个图表看起来都像是它的标准图集之一。

8. 不用符号

实际上，与迷恋符号完全相反的另一个极端已经相当普遍了。许多人完全无视UML，使用一些没人能理解的自定义符号绘制图表，并将诸如构建依赖项、数据流和部署之类的随机问题混为一谈。

9. 信息墓地

企业知识管理解决方案是知识消亡的地方。看看这些：

企业 wiki
SharePoint
大型 Microsoft Office 文档
共享文件夹
搜索功能很差的工单系统和 wiki

这些文档编写方法通常会失败，要么是因为通过它们很难找到正确的信息，要么是因为将信息保持最新状态需要大量工作，或者两者皆有。这些方法促进了只写文档（write-only documentation）或只写一次文档（write-once documentation）的形式。

在最近的一次 Twitter 交流中，著名软件开发商 Tim Ottinger（@tottinge）问了这样一个问题。

产品类别：“文档墓地”——所有文档管理、wiki、SharePoint 和团队空间是否注定失败？

James R. Holmes（@James_R_Holmes）回复如下。

我们的标准笑话是这样的：说“它在内网上”会引发“你刚刚是让我自己去____吗？”的回应。

（注意：因为原话用了粗俗的语句，所以做了编辑，你懂的。）

10. 误导性的帮助

只要文档不能严格保持最新，就会产生一定的误导性。虽然文档看起来有用，但事实上是错误的。因此，这些文档可能读起来有意思，但是辨别哪些内容仍然正确以及哪些内容已经不再正确会造成额外的认知负担。

当文档无法正确指导用户时，它就是有害的

编写高质量的文档需要很多时间，而维护它往往需要更长时间。如果一个人时间紧迫，他就会经常略过文档任务，或者快速、粗糙地完成文档。毕竟，咱们总有“比写文档更重要的事”。

然而，真实的情况是什么？开发人员经常因为缺失有效文档而“抓狂”，软件经常因为缺失有效文档而为开发人员所“诟病”。既然，文档相关的问题如此严重，是时候了解一下文档 2.0 了。

活文档

自 20 世纪 90 年代末以来，诸如整洁的代码、测试驱动开发（TDD）、行为驱动开发（BDD）、领域驱动设计（DDD）和持续交付之类的实践越来越流行。这些实践改变了我们关于软件交付的思考方式。

现在，我们终于可以期待有这样一种文档编写方法：

它实用，能使文档内容永远保持最新
成本低，并能让编写文档变得有趣

这就是活文档的核心理念，它要解决传统文档存在的问题。具体是怎么解决的呢？

西里尔·马特雷尔（Cyrille Martraire）是个创业公司的 CTO，软件设计专家，曾领导过多个重大项目，在处理大型遗留系统方面经验丰富。2013 年，在 Öredev 技术会议上首次系统提到活文档时，引发了与会人员的强烈兴趣。此后 5 年多的时间，西老师专注于系统化他这套理念，以及实践更多的方法。2019 年 5 月，西老师出版了一本书，名为Living Documentation: Continuous Knowledge Sharing by Design，图灵将这本书引入，就是今天为大家介绍的这本：《活文档：与代码共同演进》。