精益文档
Lean Documentation (原文)
Posted by Tomas Björkholm on Apr 09, 2015
我的业余研究告诉我，要实现更大的有效性和上乘的质量，最重要的三件事是知识，知识，还是知识。知识最好通过交流获得，但是只有和有知识的人交流才会有效。糟糕的是，有些情况下这样的人无法参与讨论。
My amateur research has given me the insight that the three most important things for greater effectiveness and good quality are knowledge, knowledge and knowledge. Knowledge is best acquired through a dialog but a dialog is only efficient if it includes someone with knowledge. Unfortunately, there are situations when such a person is not around.
本文会帮助你在这种只有文档是唯一的知识来源的情况下，写出有效和有用的文档。本文中介绍的实践，是基于我在一家大型跨公司参与的一个项目的经验。
This article will help you write effective and useful documentation for those situations where documentation is the only available source of knowledge. The practices presented in this article are based on my experiences working on a project at a big multinational company.
这一切都起于一位开发人员提出了一个改进项目文档的主意。我们集中了一个有志于改进文档的团队，达成对一些原则的共识。
It all started when a developer said he had an idea for improving the project documentation. We gathered a team of people who were interested in improving the documentation and agreed to a few rules.
良好文档的原则
The rules for great documentation
文档应当：
- 快速而又容易创建和更新。过时的信息比没有信息更为糟糕。
- 容易提供正确的答案。如果不容易查找，没人会使用。
- 不是要代替人与人之间的交流。人和交流，更重于过程和工具，对吗？
The documentation should:
- Be quick and easy both to create and update. Information that is out of date can be worse than no information at all.
- Easily provide correct answers. If it’s not easy to find no one will use it anyway.
- Not replace human interaction. Individuals and interaction over processes and tools, right?
为实现这些规则，我们提出了六项实践：
To reach the goal of fulfilling the rules, we set up six practices:
实践1 - 明确文档的使用者，以及使用文档的原因
Practice 1 – Identify your consumers and their reasons for using the documentation
尽管这好像很明显，但很少有人会这么做。对我们的项目来说，我们的改进小组确定了4组目标人群。
- 管理人员，他们需要我们正在做的事情的一个简短总结。
- 新的开发人员，他们需要快速的介绍。
- 系统以前的开发人员，他们在做了几年其它的事情之后回到了该项目。
- 排错人员，他们帮助解决问题。
While this sounds obvious, it is rarely done. For our project, our improvement team identified four target groups.
- Managers who need a short summary of what we’re working on.
- New developers who need a quick introduction.
- Former developers of the system who come back to the project after a few years of doing something else.
- Trouble shooters who help customers with their problems.
第一组目标人群在我们问到他们对文档的需求时表现出惊喜。首先，之前没有人问过他们这个问题。哇！其次，他们从来没有使用过他们拥有的庞大文档。这个目标人群只需要对三件事情的回答。总之，三行文档就能满足需要了。多余的对读者和作者都是浪费。吃惊吧！
The first target group was pleasantly surprised when we asked them about their documentation needs. First of all, no one had ever asked them before. Wow! Secondly, they never even used the massive documents that they had. This target group only needed the answer to three things. In total, three lines of documentation was all that was needed. The rest was waste both for the reader and the writer. OMG!
实践2 - 象谷歌地球那样组织
Practice 2 – Structure it like Google Earth
人们使用文档查找对他们心中疑问的解答。文档的质量可以用找到解答所需要的时间来衡量。我们用谷歌地球作为模型。
People use documentation to find answers to the questions they have. The quality of the documentation can be measured by the time it takes to find the answers. We used Google Earth as a model.
你有没有在谷歌地球上找过你住的房子(逐级向下浏览，而不是搜索地址)？你要花多长时间？也许30到60秒？在地球表面找到你的房子，就象在一万五千亿(1.5 × 10^12)个答案中找到一个答案。如果你查找一个答案，那不应该超过60秒，即使你的系统复杂又庞大。
Have you ever tried to find your house on Google Earth (drilling down, not searching on address)? How long did it take? Maybe 30 to 60 seconds? Finding your house on the surface of the Earth is like finding 1 answer among 1,5 trillion (1,5 * 1012) answers. If you are looking for an answer it shouldn’t take more than 60 seconds, even if your system is complex and huge.
在文档中这是怎样的？我们用在谷歌地球中的各级高度之间移动的层级类比：月亮高度，卫星高度，飞机高度，直升机高度，等等。每个级别都有一个简短的描述，我们称之为电梯演讲(elevator pitch)，最多有9种继续到下一级的可能。
How does this apply to documentation? We followed a hierarchy analogous to moving through the levels in Google Earth: moon level, satellite level, airplane level, helicopter level and so on. Each level has a short description, which we called an elevator pitch, and up to nine possibilities to continue down the next level.
要记得并非所有的文档工具都适于逐级向下浏览(drill down)的方式。一个包含Word文档的目录结构就可能不是个好主意。而含有指向下一级的链接的维基(wiki)就好得多。
Keep in mind that not all documentation tools are well suited for a drill down approach. A directory structure with Word documents is probably not a good idea. A wiki with links to next levels is much better.
实践3 - 保持精简
Practice 3 – Keep it small
我们讨论了产生文档的理由，提出了下面尽可能减小文档的原则：
- 文档应当是不受限于时间和空间的交流。这不应当代替实时的交流。
- 我们应当记录结果，而非需求。这意味着我们在发布新功能时更新或替换文档，而不是在获得需求时添加文档。这样保证文档准确地反应了系统的当前状态。
- 文档的好处必须超过创建和维护它的代价。不要浪费时间来记录已经写成代码的东西。文档应当提供大尺度的概述，以及有足够的信息能够帮助读者快速找到必要的代码。
We discussed the reason for documentation and come up with the following principles to minimize the size:
- Documentation should be communication without constraints in time or location. It’s not a replacement for communication in real time.
- We should only document results not requirements. That means we update or replace the documents when we launch new functionality instead of adding new documents when we get the requirements. This approach ensures that the documentation accurately reflects the current state of the system.
- The benefit of having documentation must be greater than the cost of creating and maintaining it. Don’t waste time on documenting what is already written as code. The documentation should provide a big picture overview, and enough information to help the reader quickly find the necessary code.
保证适量的文档，是在太短而无用和太长而难读之间的平衡。如果你不使用文档，你就不会去更新它，那它就失去存在的价值，更糟的是，如果文档陈旧而且引人误入歧途，那就反而有害了。
Having the right amount of documentation is a balance between too short to be useful and too long to read. If you don’t use it, you will not update it and then it’s worthless or even worse harmful if it’s old and misleading.
下面是我从 Henrik Kniberg 得到的建议：
- 保持尽可能少的文档 - 但不能更少了
- 保持文档尽可能短 - 但不能更短了
就是这么简单 :-)。
Here is the advice I got from Henrik Kniberg:
- Have as few documents as possible – but not fewer
- Have as short documents as possible – but not shorter
It’s that easy :-).
实践4 - 文字要引人入胜
Practice 4 - Make the text inviting to read
大段的不痛不痒的文字是乏味的。如何让文字更切中要害呢？
Long, irrelevant text is boring. How can you make your text relevant?
我们做了如下尝试：我们让一个潜在的用户询问具有知识的某人。读者比专家更知道他们要了解什么，如何组织文字。专家只能猜测读者想要了解什么，以及应当如何组织。
We tried this: We asked a potential consumer to interview someone with knowledge. The reader knows what they want to know and how to structure the text better than the expert. The expert can only guess what the reader wants to know and how it should be structured.
一个典型的反面模式是当一个人要离开公司时，他们的经理就会让他们把在公司的剩余时间用于记录他们所知道的一切。对大多数人来说，这更象是惩罚，而不是创造价值的工作。
A typical anti pattern is when someone is leaving the company and their manager asks them to spend their remaining time at the company documenting everything they know. For most people that is more of a punishment than value adding work.
实践5 - 融入可视元素
Practice 5 – Incorporate visuals
尽管文字应当简短，但是随着层次进一步深入，在最低一级，文字就可能需要更长，包含更多细节。这里要怎么做才能防止读者流失？要使用科普的方式。与其把你的文档写得象科学报告，不如采用科普杂志使用的更易于接受的方式，包含大量可视化元素和简短易读的段落。
Even though the text should be short, further down in the hierarchy, on leaf level, the text might need to be longer and contain more detail. How can this be done without losing the reader? Popular Science to the rescue! Rather than writing your documentation like a scientific report, use the approachable style that Popular Science magazine uses, with lots of visual elements and short easy to read paragraphs.
增加可视化元素可以帮助文档的读者快速找到他们需要的内容。读者的视线会从一张图片跳到另一张图片，就象阅读报纸一样。
Adding visuals helps your documentation consumers find what they need quickly. The reader’s eyes will go from picture to picture just like when you read a newspaper.
实践6 - 使其便于维护
Practice 6 - Make it easy to maintain
撰写良好的文档最大的挑战在于保持更新的状态。
The biggest challenge in writing good documentation is to keep it up to date.
这要求一些纪律和一条简单的童子军(Boy Scout)规则，“总是保持营地比你发现时更干净”。在文档中，这意味着：如果一份文档没有给你需要的信息－一经发现就用正确的信息更新。
This requires some discipline and a simple Boy Scout rule, “always leave the campground cleaner than you found it.” In documentation this means: if the document does not give you the information you need – update it with the correct information as soon as you have figured it out.
保持文档更新的可能性，随着修改的地方和写文档的地方之间的距离增加而递减。代码中的注释离改动更近，所以比在另外一个工具中的文档更有可能被更新。如果你使用维基(wiki)撰写文档，就可以轻易地整合代码中的注释。
The likelihood of maintaining up-to-date documentation decreases as the distance between what you change and where to document increases. Comments in code are closer to the change so they are more likely to be updated than a document in another tool. If you use a wiki for your documentation you can easily integrate comments in code.
如果文档很难更新，或者不能随着问题的发现而及时更新，那么它就不太可能被更新。请使用一款工具来容易地甚至同步地更新(文档)。这同样适用于图像，所以确保使用一款能够直接在其中创建和更新图像的工具。使用PlantUML的MediaWiki，和使用Gliffy的Confluence，就是两个例子。
If the documentation is difficult to update, or can’t be updated as soon as an issue is detected, it’s less likely to be updated. Use a tool for easy updates or even simultaneous updates. The same goes for images so make sure to use a tool that creates and updates images directly in the tool. MediaWiki with PlantUML and Confluence with Gliffy are two examples.
结果
The result
当位于另外一个城市的一个团队需要修改通常由我们的部门维护的代码时，我们的文档系统经受了考验。一段简短的介绍和一封含有文档位置的链接的电子邮件，就是我们之间唯一的通讯，相当出乎我们意料的是，所有需要的交流也就是这点儿了。我们达到了我们的目的。我么有了快速易于创建和维护的文档系统，而这帮助用户找到他们所需要的解答。
Our documentation came to a test when a new group of people working in another city needed to change code that is usually maintained by our department. A short introduction and an e-mail with a link to the documentation area was the only contact we had and much to our surprise that was also all that was needed. We had reached our goal. We had documentation that was quick and easy to create and maintain, and that effectively helped users find the answers they needed.
我希望我们的原则和实践也能够帮助你创建更好的文档。
I hope our rules and practices can help you create better documentation.
祝你好运！
Good luck!
声明：标题中的精益(Lean)和丰田制造商没有任何关系。这只是我所使用的形容词 lean (意味着：有效率，没有浪费)。
Disclaimer: Lean in the title has nothing to do with the car manufacturer Toyota. It is the adjective lean (meaning: efficient and with no wastage) I’m referring to.
要感谢 Ellen Gottesdiener 的支持和帮助。感谢 Jonas Boegård, Henrik Rasmussen 和 Igor Soloviev 提供的好主意。也要感谢 Mia Starck 和 Yassal Sundman 对文字的帮助。
Thanks to Ellen Gottesdiener for her support and help. Thanks to Jonas Boegård, Henrik Rasmussen and Igor Soloviev for all their good ideas. Thanks also to Mia Starck and Yassal Sundman for their help with the language.
注：在第一段中提到的“知识，知识，还是知识”指：领域知识 (了解业务)，系统知识 (了解系统的领域和架构)，以及近期的产品需求知识 (知道我们正在构建的东西)。本文介绍的文档方法最适用于领域知识和系统知识，以及如何弥合二者之间的间隙。
Note: the “knowledge, knowledge and knowledge” mentioned in the first paragraph refer to: domain knowledge (knowing the business), system knowledge (knowing the domain and architecture of the system) and immediate product need knowledge (knowledge about what we are building right now). The documentation methods described in this article are best suited to domain and system knowledge, and to bridging the gap between the two.
关于作者
About the Author
Tomas Björkholm 在瑞典斯德哥尔摩的Crisp公司任职敏捷教练和培训师。他热衷于培训团队，特别是大企业中的团队。他的使命是让敏捷方法容易理解和适应。Tomas 写了两本书，瑞典文的《敏捷方法向导》，和即将出版的《30天学会Kanban开发》。
Tomas Björkholm works as an Agile coach and trainer at Crisp in Stockholm, Sweden. He has a great passion for growing teams especially within large enterprises. His mission is to make Agile easy to understand and to adapt. Tomas has written two books, a guide to Agile in Swedish and the soon to come “Kanban development in 30 days”.
参考资料
- LEAN 公司内部资料 精讲+案例介绍 (154页PPT)_百度文库http://wenku.baidu.com/link?url=MVr46YQcbCnAOT06PKoE4Mb8rUhUVcMZJVRBzAOWUseCOCA6DygeC4jT15czmBohaukolT1hEPvYkcS9WzLYgHpnCGmVX43dj3rlaUQ0H7q