如何撰写好文档？精益文档的六个实践-InfoQ

我在业余时间的一项调研让我洞察到对高效率和高质量最重要的三件事就是知识、知识还是知识。最好的知识获取途径就是通过对话，与了解这方面知识的人的对话。不幸的是，很多情况下这样的人并不在身边。

当文档是唯一的知识传承手段时，本文将尝试帮助读者编写有效而实用的文档。本文中所展示的实践都是基于我在一家大型跨国公司的项目中的工作经验。

这一切源于一个开发人员对我说他有一个改善项目文档的想法。我们就集合了一组对改善文档感兴趣的人并就一些规则达成了一致。

好文档的规则

好的文档应该：

能够快速方便地创建和更新。过时的信息比没有信息更可怕。
能够方便地提供正确答案。如果不能很方便地找到答案，就不会有人愿意使用。
不要代替人的交互。单独的个体和通过流程和工具的交互，这样对吗？

为了达成能够满足上述规则的目标，我们制定了六个实践：

实践一——识别阅读文档的用户以及他们使用文档的原因

尽管这听起来显而易见，但是很少有人真正这么做。在我们的项目中，我们的改进团队识别了四个目标群组。

需要我们的工作内容的简短总结的经理
需要快速介绍的新加入的开发人员
经过几年其它项目之后重返当前项目的原系统开发人员
帮助客户解决问题的故障排除人员

当我们问起他们对文档的需求是，第一个目标群组用户相当惊喜。首先，之前从未有人问过他们。哇！其次，他们甚至从未使用过他们所拥有的大量文档。这一目标群组只需要三件事情的答案。总的来说，他们所需要的就是三行文档。其他的文档对于读者和编者都是浪费时间。我的天！

实践二——像 Google Earth 那样组织文档

用户使用文档是为了找到他们的问题的答案。可以通过找到正确答案所需要的时间来衡量文档的质量。我们用 Google Earth 作为模型。

你是否曾试图在 Google Earth 上找到你的房子（通过下钻而不是搜索地址的方式）？它花费了你多长时间？大概 30 到 60 秒？在地球表面找到你的房子就像在 1.5 万亿（1.5*1012）个答案中找到其中一个答案一样。即使系统十分复杂庞大，找到答案的时间也不应该超过 60 秒。

如何将这一模型应用到文档上呢？我们遵循了类似于 Google Earth 移动层级的层次结构：月亮级、卫星级、航拍级和直升机级等。每一层级都有一个简短的介绍，我们称之为电梯间演讲，而且延续到下一层最多只有九种可能。

记住，并非所有的文档工具都适于下钻的方法。包含目录结构的 Word 文档可能就不是一个很好的主意。有指向下层链接的 wiki 就好很多。

实践三——保持小规模

我们讨论了文档化的原因并得出如下最小化文档规模的原则：

文档应该是没有时间和位置限制的沟通方式。不应该是实时沟通的替代品。
我们应该只留存结果而非需求。也就是说只有在推出新功能时，我们才更新或替换文档而不是在拿到需求时就新增文档。这样就能确保文档能够准确地反映当前的系统状态。
文档所带来的收益必须要大于创建和维护它的成本。不要将时间浪费在文档化那些已经写成代码的知识上。文档应该提供一个全局概览和足够的能够帮助读者快速找到必要代码的信息。

适量的文档就是在太短以致不实用和过长以致影响阅读之间找到平衡。如果你不使用它，也就不会去更新它，而如果文档过于陈旧并会产生误导，也就变的毫无价值甚至会造成损失。

这是我从 Henrik Kniberg 那里得来的一些忠告：

文档数量越少越好—但不能更少
文档长度越短越好—但不能更短

就这么简单：）

实践四——让文字读起来更吸引人

冗长、不切题的文档读起来让人厌烦。如何才能让文档更切题？

我们尝试过这种办法：我们请潜在的使用者与具有该知识的人进行面谈。读者比专家更知道他们想要什么以及应该如何组织文字。而专家只能猜想读者想要了解什么以及文字应该如何组织。

一个典型的反模式就是当员工要离开公司时，经理请他们在剩余的这段时间里将他们所知道的全部知识都写成文档。对大多数人来说这更像是一种惩罚而不是增值的工作。

实践五——结合可视化元素

尽管文档应该尽量简洁，不过当层次结构更加深入，在叶子层级的文档可能需要稍长一些并且应该包含更多细节。如何能够在不失去读者的前提下完成这项工作？不要把文档写的像一篇科学报告一样，要用科普杂志那种更容易理解的风格，包含足够多的可视化元素和简短易读的段落。

增加可视化元素能够帮助文档使用者快速找到他们所需要的知识。就像读报纸一样，图片会更吸引读者的眼球。

用图片帮助读者找到合适的段落

实践六——让文档易于维护

写好文档的最大挑战就是一直让文档处于最新状态。

这需要一些训练和一条简单的 Boy Scout 规则，“总是让营地比你发现它时更整洁。”在文档中这就意味着：如果文档没有提供给你所需要的信息——只要你一找到正确信息就尽快把它更新到文档中。

所做出的修改与相应的文档记录之间距离越远，保持文档更新的可能性就越低。代码中的注释距离修改更近，所以相对来说就比在另外一个工具中记录的文档更有可能被更新。如果用 wiki 记录文档，很容易就可以将代码中的注释集成到 wiki 中。

如果文档难以更新，或者不能在发现问题时及时更新，就很可能不会被更新。使用可以更容易更新或甚至可以同步更新的工具。图片也是一样，因此确保要使用一个可以在工具中直接创建和更新图片的工具。带有 PlantUML 扩展的 MediaWiki 和带有 Gliffy 插件的 Confluence 就是两个比较好的例子。

结果

当在另一个城市工作的新团队需要修改之前由我们的部门维护的代码时，我们的文档接受了真正的测试考验。一个简短的介绍和一封包含指向文档区域的链接的电子邮件就是我们之间唯一的接触，而让我们相当惊奇的是这也是所需要的全部接触。我们成功达成了目标。我们有了可以快速方便地创建和维护的文档，而且这些文档也能够有效地帮助使用者找到他们所需要的答案。

希望我们的规则和实践能够帮助你创建更好的文档。

祝你好运！

免责声明：标题中的“精益”与汽车制造商丰田无关。我所指的是形容词精益（含义：高效、无浪费）。

感谢 Ellen Gottesdiener 的支持和帮助。感谢 Jonas Boegård，Henrik Rasmussen 和 Igor Soloviev 的好主意。同时感谢 Mia Starck 和 Yassal Sundman 在语言方面的帮助。

注：在第一段中所提及的“知识、知识还是知识”指的是：领域知识（了解业务）、系统知识（了解系统的领域和架构）和即时的产品需求知识（与我们目前正在创建的功能的相关知识）。本文中所描述的文档化方法最适于领域和系统知识，并且可以在这两者之间建立桥梁。

关于作者

Tomas Björkholm在瑞典斯德哥尔摩的 Crisp 公司担任敏捷方法的教练和训练员。他对不断成长的团队，特别是大型企业中的团队，有着巨大的热情。他的使命是让敏捷方法更易于理解和采用。Tomas 著有两本著作，瑞典语版本的《敏捷方法指南》和即将出版的《30 天学会 Kanban 开发》。