[翻译] 精益文档
精益文档
作者
本文会帮助你在这种只有文档是唯一的知识来源的情况下，写出有效和有用的文档。本文中介绍的实践，是基于我在一家大型跨公司参与一个项目时的经验。
这一切都起于一位开发人员提出了一个改进项目文档的主意。我们集中了一个有志于改进文档的团队，达成对一些原则的共识。
优秀文档的原则
文档应当：
- 快速而又易于创建和更新。过时的信息比没有信息更为糟糕。
- 易于提供正确的答案。如果不容易查找，没人会使用。
- 不是要代替人与人之间的互动。个体和互动，高于流程和工具，对吗？
为了实现这些原则，我们提出了六项实践：
实践1 - 明确文档的使用者，以及使用文档的原因
尽管这好像很明显，但很少有人会这么做。对我们的项目来说，我们的改进小组确定了4组目标人群。
- 管理人员，他们需要我们正在做的事情的一个简短总结。
- 新的开发人员，他们需要快速的入门介绍。
- 系统以前的开发人员，他们在做了几年其它的事情之后又回到了该项目。
- 排错人员，他们帮助客户解决问题。
第一组目标人群在我们问到他们对文档的需求时表现出惊喜。首先，之前没有人问过他们这个问题。哇！其次，他们甚至从来没有使用过他们拥有的庞大文档。这个目标人群只需要对三件事情的回答。总之，三行文档就足够了。多余的对读者和作者都是浪费。吃惊吧！
实践2 - 象谷歌地球那样组织
人们使用文档查找对他们心中疑问的解答。文档的质量可以用找到答案所需要的时间来衡量。我们用谷歌地球作为模型。
你有没有尝试过在谷歌地球上找你的房子(逐级向下浏览，而不是搜索地址)？你花了多长时间？也许30到60秒？在地球表面找到你的房子，就象在一万五千亿(1.5 × 10^12)个答案中找到某一个答案。如果你查找一个答案，那不应该超过60秒，即使你的系统复杂又庞大。
在文档中这是怎样的？我们用在谷歌地球中的各级高度之间移动的层级进行类比：月亮高度，卫星高度，飞机高度，直升机高度，等等。每个级别都有一个简短的描述，我们称之为电梯演讲(elevator pitch)，最多有9种继续到下一级的可能。
要记得并非所有的文档工具都适于逐级向下浏览(drill down)的方式。一个包含Word文档的目录结构就可能不是个好主意。而含有指向下一级链接的维基(wiki)就好得多。
实践3 - 保持简短
我们讨论了使用文档的，提出了下面保持最少量文档的原则：
- 文档应当是不受限于时间和空间的交流。这不应当代替实时的交流。
- 我们应当只记录结果，而非需求。这意味着我们在发布新功能时更新或替换文档，而不是在获得需求时添加文档。这种方式保证文档准确地反应了系统的当前状态。
- 文档的好处必须超过创建和维护它的代价。不要浪费时间来记录已经写成的代码。文档应当提供大尺度的概述，以及有足够的信息能够帮助读者快速找到必要的代码。
保证适量的文档，是在太短而无用和太长而难读之间的平衡。如果不使用文档，就不会去更新它，那它就失去了存在的价值，甚至更糟的是，如果文档陈旧而且引人误入歧途，那就反而有害了。
下面是我从Henrik Kniberg得到的建议：
- 保持尽可能少的文档 - 但不能更少了
- 保持文档尽可能短 - 但不能更短了
就是这么简单 :-)。
实践4 - 文字要引人入胜
大段的不痛不痒的文字是乏味的。如何让文字更切中要害呢？
我们做了这样的尝试：我们让一个潜在的用户询问具有知识的某人。读者比专家更知道他们要了解什么，如何组织文字。专家只能猜测读者想要了解什么，以及应当如何组织。
一个典型的反面模式是当一个人要离开公司时，他们的经理就会让他们把在公司的剩余时间用于记录他们所知道的一切。对大多数人来说，这与其说是创造价值的工作，不如说是惩罚。
实践5 - 融入可视元素
尽管文字应当简短，但是随着层次进一步深入，在最低一级，文字就可能需要更长，包含更多细节。这里要怎么做才能防止读者流失？要使用科普所采用的方式！与其把你的文档写得象科学报告，不如采用科普杂志使用的更易于接受的方式，包含大量可视化元素和简短易读的段落。
增加可视化元素可以帮助文档的读者快速找到他们需要的内容。读者的视线会从一张图片跳到另一张图片，就象阅读报纸一样。
实践6 - 使其便于维护
撰写良好的文档最大的挑战在于保持更新的状态。
这要求一些纪律和一条简单的童子军(Boy Scout)规则，“总是保持营地比你发现时更干净”。在文档中，这意味着：如果一份文档没有给你需要的信息－一经发现就用正确的信息更新。
保持文档更新的可能性，随着修改的地方和写文档的地方之间的距离增加而递减。代码中的注释离改动更近，所以比在另外一个工具中的文档更有可能被更新。如果你使用维基(wiki)撰写文档，就可以轻易地整合代码中的注释。
如果文档很难更新，或者不能随着问题的发现而及时更新，那么它就不太可能被更新。请使用一款工具来容易地甚至同步地更新(文档)。这同样适用于图像，所以确保使用一款能够直接在其中创建和更新图像的工具。使用PlantUML的MediaWiki，和使用Gliffy的Confluence，就是两个例子。
结果
当位于另外一个城市的一个新的团队需要修改通常由我们的部门维护的代码时，我们的文档系统经受了考验。一段简短的介绍和一封含有文档位置的链接的电子邮件，就是我们之间唯一的通讯，相当出乎我们意料的是，这就足够了。我们达到了我们的目的。我们有了快速易于创建和维护的文档系统，而这的确帮助用户找到了他们所需要的解答。
我希望我们的原则和实践也能够帮助你创建更好的文档。
祝你好运！
声明：标题中的精益(Lean)和汽车制造商丰田没有任何关系。这只是我所使用的形容词lean(意味着：有效率，没有浪费)。
要感谢Ellen Gottesdiener的支持和帮助。感谢Jonas Boegård、Henrik Rasmussen和Igor Soloviev提供的好主意。也要感谢Mia Starck和Yassal Sundman对文字的帮助。
注：在第一段中提到的“知识，知识，还是知识”指：领域知识 (了解业务)，系统知识 (了解系统的领域和架构)，以及近期的产品需求知识 (知道我们正在构建的东西)。本文介绍的文档方法最适用于领域知识和系统知识，以及如何弥合二者之间的间隙。
关于作者
Tomas Björkholm在瑞典斯德哥尔摩的Crisp公司任职敏捷教练和培训师。他热衷于组建团队，尤其是大企业中的团队。他的使命是让敏捷方法容易理解和适应。Tomas写了两本书，瑞典文的《敏捷方法向导》，和即将出版的《30天掌握Kanban开发》。
参考资料
- LEAN 公司内部资料 精讲+案例介绍 (154页PPT)_百度文库
http://wenku.baidu.com/link?url=MVr46YQcbCnAOT06PKoE4Mb8rUhUVcMZJVRBzAOWUseCOCA6DygeC4jT15czmBohaukolT1hEPvYkcS9WzLYgHpnCGmVX43dj3rlaUQ0H7q - 敏捷软件开发宣言
http://agilemanifesto.org/iso/zhchs/
