标签：
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 documentation should:
为实现这些规则，我们提出了六项实践：
To reach the goal of fulfilling the rules, we set up six practices:
尽管这好像很明显，但很少有人会这么做。对我们的项目来说，我们的改进小组确定了4组目标人群。
While this sounds obvious, it is rarely done. For our project, our improvement team identified four target groups.
第一组目标人群在我们问到他们对文档的需求时表现出惊喜。首先，之前没有人问过他们这个问题。哇！其次，他们从来没有使用过他们拥有的庞大文档。这个目标人群只需要对三件事情的回答。总之，三行文档就能满足需要了。多余的对读者和作者都是浪费。吃惊吧！
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!
人们使用文档查找对他们心中疑问的解答。文档的质量可以用找到解答所需要的时间来衡量。我们用谷歌地球作为模型。
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.
我们讨论了产生文档的，提出了下面尽可能减小文档的原则：
We discussed the reason for documentation and come up with the following principles to minimize the size:
保证适量的文档，是在太短而无用和太长而难读之间的平衡。如果你不使用文档，你就不会去更新它，那它就失去存在的价值，更糟的是，如果文档陈旧而且引人误入歧途，那就反而有害了。
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:
It’s that easy :-).
大段的不痛不痒的文字是乏味的。如何让文字更切中要害呢？
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.
尽管文字应当简短，但是随着层次进一步深入，在最低一级，文字就可能需要更长，包含更多细节。这里要怎么做才能防止读者流失？要使用科普的方式。与其把你的文档写得象科学报告，不如采用科普杂志使用的更易于接受的方式，包含大量可视化元素和简短易读的段落。
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.
撰写良好的文档最大的挑战在于保持更新的状态。
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.
当位于另外一个城市的一个团队需要修改通常由我们的部门维护的代码时，我们的文档系统经受了考验。一段简短的介绍和一封含有文档位置的链接的电子邮件，就是我们之间唯一的通讯，相当出乎我们意料的是，所有需要的交流也就是这点儿了。我们达到了我们的目的。我么有了快速易于创建和维护的文档系统，而这帮助用户找到他们所需要的解答。
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.
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”.
标签：
原文地址：http://www.cnblogs.com/blackpuppy/p/lean_documentation.html
