原文出
处：http://www.infoq.com/cn/article
s/practices-lean-documentation
我在业余时间的一项调研让我洞察到
对高效率和高质量最重要的三件事就
是知识、知识还是知识。最好的知识
获取途径就是通过对话，与了解这方
面知识的人的对话。不幸的是，很多
情况下这样的人并不在身边。
当文档是唯一的知识传承手段时，本
文将尝试帮助读者编写有效而实用的
文档。本文中所展示的实践都是基于
我在一家大型跨国公司的项目中的工
作经验。
这一切源于一个开发人员对我说他有
一个改善项目文档的想法。我们就集
一些规则达成了一致。
实践一——识别阅读文档的用
户以及他们使用文档的原因
实践二——像Google Earth那样
组织文档
实践四——让文字读起来更吸
引人
好文档的规则
好的文档应该：
能够快速方便地创建和更新。过
时的信息比没有信息更可怕。
能够方便地提供正确答案。如果
不能很方便地找到答案，就不会
有人愿意使用。
不要代替人的交互。单独的个体
和通过流程和工具的交互，这样
对吗？
为了达成能够满足上述规则的目标，
我们制定了六个实践：
实践一——识别阅读文档的
用户以及他们使用文档的
原因
尽管这听起来显而易见，但是很少有
人真正这么做。在我们的项目中，我
们的改进团队识别了四个目标群组。
需要我们的工作内容的简短总结
的经理
需要快速介绍的新加入的开发人
员
经过几年其它项目之后重返当前
项目的原系统开发人员
帮助客户解决问题的故障排除人
员
当我们问起他们对文档的需求是，第
一个目标群组用户相当惊喜。首先，
之前从未有人问过他们。哇！其次，
他们甚至从未使用过他们所拥有的大
量文档。这一目标群组只需要三件事
情的答案。总的来说，他们所需要的
就是三行文档。其他的文档对于读者
和编者都是浪费时间。我的天！
实践二——像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开发》。
查看英文原文： Lean Documentation
原文出
处：http://www.infoq.com/cn/article
s/story-driven-docs
在OutSystems，我们创建了一个平
台，旨在简化应用程序整个生命周期
的管理流程。但是，对于用户而言，
我们的文档却不简单。
我们的文档侧重于描述UI（用户界
面）提供的每个按钮，而不是用户的
意图和目的。
一个明显的例子是，对于文本查找功
能（CTRL+F），我们有一整页的文
档。这页文档详细描述了UI提供的每
一种选项，其详细程度令人难以忍
受：
区分大小写、不区分大小写
全词匹配
细化搜索范围
我们专注于这些不言自明的选项，但
却没有告诉用户如何找到他们需要的
东西：
如何找出所有具有给定名称的元
素；
如何找出所有影响标题的CSS规
则；
如何找出所有针对特定数据库表
的查询。
对我们而言，维护文档非常困难。
OutSystems平台不断变化，我们跟不
上它的节奏。
更重要的是，我们没有满足用户的需
求。这从个位数的页面访问量和我们
从部分客户那里得到的反馈很容易看
出来。
在本文中，我将讨论如何停止编写UI
文档，并开始提供用户故事驱动的文
档。
现在，我们专注于用户想要实现什么
以及他们可以如何实现，这与他们需
要用到多少窗口或按钮无关。我们还
可以更好地排定工作优先级，那样一
来，最常用的用户故事会获得更多的
关注和资源。
我将讨论以下几个方面的内容：
为什么要避免编写UI文档；
如何检查你当前是否是在编写UI
文档；
为什么用户故事是一种更好的产
品文档编写方式；
专注于用户故事如何改变了我们
团队的文化，使我们可以从事真
正重要的工作。
那么让我们开始吧。
为什么要避免编写UI
文档
编写UI文档可能使用户更难以理解你
的产品，这显而易见。这样做也可能
不利于你和你的团队，但这就不是那
么容易理解了。
所以，我们首先重点讨论下对用户的
影响，然后再探讨下给你和你的团队
带来的一些后果。
如果你编写的是UI文档，即使用户找
到了正确的文档，他们也无法获得完
成一项任务所需的所有上下文。
这对于新用户和专家用户而言都会带
来困难：
新用户——他们无法理解概念之
间的关联关系以及如何搭配使用
现有工具解决问题；
专家用户——他们会在查找参考
文档方面遇到困难，因此，他们
需要诉诸于试验。
新用户的日子会不好
过
使用CRTL+F查找什么东西非常简
单，但是大多数任务，比如查询数据
库表，需要了解若干概念以及它们彼
此之间的关联关系。
因此，对于首次接触的新用户而言，
即使是简单的任务，看上去也会很
难。以我们的文档为例，我们有大约
3页文档解释如何查询一张数据库
1
表。即使新用户非常有耐心，并且读
完了所有的文档，他们还是会很难理
解如何获取数据。
更重要的是，他们很难理解如何搭配
使用所需的工具在页面上展示查询结
果。
虽然OutSystems有一个可视化的开发
环境，但这还是很让我失望。这是因
为，查询数据并展示在页面上只需三
次拖放外加两次鼠标点击。唉，采用
复杂的方式来做，才会这么麻烦。否
则，一次拖放就够了。
专家用户的日子会不
好过
专家用户的日子也不会轻松。当集中
注意力编写UI文档时，你很难将需要
组织到用户指南中的信息和应该作为
参考的信息区分开。在你看来，所有
东西都像参考。
最终，你会将所有的东西都混在一
起，即使是经验丰富的用户，要找到
他们正在查找的详细说明，也变得更
加困难。
搜索引擎很难将流量
导向文档
即使你编写的文档适合新用户及专家
用户，如果用户无法找到你的文档，
那么你所有的努力也都会白费。
因为当你编写UI文档时，文档的内容
和标题反映的是：
你命名的功能名称；
窗口的标题或名称；
按钮标签。
对SEO（搜索引擎优化）而言，那可
能不是最好的选择。
以我们为例，我们将查找功能的文档
页命名为“Find Tool”。这个名字仅仅
描述了用户能够从界面上看到的东
西。因此，对于用户而言，这一页几
乎没什么价值。
对于其它的文档页，情况也没多好。
由于内容与用户需求不匹配，所以它
最终也没有包含用户查找的关键词。
因为当你集中注意力编写UI文档时，
文档中不会包含用户查找的关键词，
所以文档在搜索引擎中的排名不够
高，用户无法找到。
如果没有一个好的页面标题，即使文
档排名更高也可能没用。搜索引擎会
将页面标题作为搜索结果的一部分显
示。如果页面标题与用户的心理模型
不匹配，那么他们可能不会点击那个
可以将他们导向文档的链接。
你和你的团队的日子
也会不好过
当你编写UI文档时，每个任务、窗口
和按钮对你而言都同等重要。
当所有东西的重要性都相同时，就很
难排定工作优先级。这很危险，尤其
是当你正奔向里程碑时。作为一个副
作用，你将会很为难地接受这样的现
实，就是可以不为那些对系统运行而
言微不足道的任务编写文档。
功能稍有变化（比如按钮标签或在界
面中的位置稍稍改变），你就会想马
上更新文档。我不是主张你应该放着
文档不管。但对我们而言，这意味着
一个永不完结的文档维护待办事项列
表。
整个方法让团队很难做战略层面的思
考。很快，你就会将更多的精力放在
内部流程中，努力缩短文档维护待办
事项列表，而不是致力于对于用户而
言重要的东西。
如何检查你是否正在
编写UI文档
关键的问题是没有客户或涉众能够直
接告诉你你正在编写UI文档。假如有
什么没能发挥作用，这会让你更难以
准确地找到解决问题的方法。
但从我们的经验来看，下面一些迹象
可能可以说明你正在编写UI文档：
你的客户抱怨，他们无法将系统
中的各个点联系起来，或者对于
如何协调多个可用的工具没有一
个总览视图；
文档的每一部分都像是参考；
许多文档页描述了相同但稍有变
化的内容；
部分页面的页面访问量或平均阅
读次数一直很少，而对于如何做
出改变，你没有一点头绪；
你有一个很长的文档维护待办事
项列表，妨碍了你做战略层面的
思考。
上述所有症状我们都有，但却不知道
做什么才能解决它们。我们认为，所
有这些问题都是孤立的，每个问题可
以使用单独的方案来解决。
我们如何开始做出改
变
从发现我们正在编写UI文档，到弄清
楚我们能够做什么，是一段很长的
路。下面，我将简单介绍一下我们努
力改变OutSystems平台文档编写流程
和方式的过程。
2012年5月
大约在2012年5月，作为OutSystems平
台的一部分，我们推出了一款新的生
命周期管理工具。但这次，我们采用
了一种不同的理念来处理这个文档项
目。
我们与开发团队、产品经理、支持人
员坐在一起，收集这个工具处理的用
户故事。我们识别出了大约18个用户
故事，但只有12个是关键的。其它6
个要么由主用户故事稍做变化得来，
要么是工具未能很好处理的边缘情
况。
我们开始注意到，对于这个项目，排
定优先级并不容易。由于用户故事构
建在其它用户故事的基础上，我们处
理事情的顺序很自然地就确定了。随
着最后期限越来越近，我们开始倾向
于推迟低优先级的用户故事。如果有
更重要的问题需要处理，那么我们可
以在产品发布之后交付剩余的文档。
另外，我们还倾向于压根不编写文
档，而是等待用户的反馈。
然后，我们有点退步。我们团队内部
发生了一些变化，我们开始设计一个
新的在线培训。这是一个大项目，我
们需要将大部分资源都投入进去。因
此，在那段时间里，我们无法对文档
做重大修改。
2
014年5月
我们正向着下一个主要版本迈进。短
暂的失望过后，我们看到可以提供更
好的文档，我与我们的团队分享了一
些我认为令人赞叹的文档项目。
我向他们展示，我们可以做得更好，
我们只需要投入精力去做。
但我知道，要改变我们交付文档的方
式，这还不够。因此，我还向团队展
示了，我是如何为我们推出的其中一
项主要功能编写几乎所有的文档。我
编写的文档中只有用户故事，我并没
有试图编写UI文档。
通过宣传推动，大家一致同意在为其
它旗舰特性编写文档时使用用户故
事。但我们没有创建任何流程或风格
指南来确保我们都交付用户故事。因
此，对于部分较小的特性，其文档中
混合了用户故事和UI。
2014年10 月
我们发布了从5月份就开始编写的文
档版本，我们都累坏了。
我们决定停下来，做一个团队回顾。
每个团队成员准备一段20分钟的演
讲，内容是关于他们在该版本发布之
前的6个月里所参与的项目。对于每
个项目，每个团队成员还需要指出三
件进展顺利的事以及三个还能改进的
地方。
我写过一篇文章，详细介绍那次回
顾，但总体上我们认为，使用用户故
事让我们：
能够在到达Beta里程碑之前交付
文档；
现有的文档得到明显改善；
更具生产力，因为更容易排定工
作优先级了。
另外，总的来说，专注于用户故事还
使我们团队同开发团队之间的讨论更
专注、更简单。
我们只是需要结构化我们处理项目的
方式，因为每个团队成员都有自己的
流程。结构化将使项目管理更简单，
使我们可以在将来的项目中节省时
间。
我们现在的文档编写
流程
那次回顾之后，我们一致同意使用下
面的五步流程进行迭代：
及早开始，经常对开发团队进行
随访；
检查是否是开始创建文档和培训
材料的恰当时机；
动手测试新特性；
编写文档草稿，并要求涉众反
馈；
如果需要，进一步修饰文档并要
求反馈。
及早开始并经常随访
在OutSystems，开发团队会在项目开
始前主持召开一个项目启动会议。每
个团队都会邀请我们及其它涉众，因
此，我们知道每个团队正在做什么。
然后，我们会分析团队收集的用户故
事，并查看他们创建的设计文档。如
果我们对一个用户故事有不同意见，
那么我们会同开发团队和产品管理部
门一起评审，确保我们只提供最重要
的用户故事。
找出开始编写文档的
恰当时机
由于大多数团队都混合使用SCRUM
和看板，所以他们还会在每个冲刺之
后演示新进展。这些接触点使我们可
以评估团队有多大进展，并检查下，
开始为新特性编写文档及培训材料是
否合适。
时机必须恰当。如果介入过早，那么
我们会为容易变化的特性编写文档。
如果介入太晚，那么我们就有延期交
付文档的风险。更重要的是，我们会
冒着无法向开发团队提供反馈的风
险，而他们可能会为用户创建特性。
测试新特性并反馈
当我们认为时机恰当时，我们从开发
团队那里获取一个构建版本，并尝试
针对新特性执行用户故事。
我们实现了一些概念验证，只是为了
通过尝试找出在文档中讲故事的最佳
方式。例如，关于从数据库提取数据
的文档是否应该关注提取客户、订
单、票据或其它信息？
在积累了一些新特性的使用经验后，
我们还会同开发团队分享我们的反
馈。我们可以借此准确地指出什么情
况让新特性难以学习和使用。例如，
认识到从多个表查询数据的方式并不
直观，了解到某个特定属性的用途，
或者一条错误消息试图传达的信息。
创建文档草稿
然后，我们开始为新特性编写文档草
稿。通常，我们会协同使用多种编辑
工具，如Google文档，并避免使用标
记、截屏或其它任何让我们从试图阐
释的用户故事分心的东西。
接下来，在我们团队和实现特性的开
发团队内部将展开一轮“20%”反馈。
这轮反馈的目标是，确认用户故事和
我们用于阐释用户故事的示例是否明
确。
修饰文档
最后，在我们都认为用户故事合理、
叙事良好之后，我们会评审和修饰文
档。我们会做一些编辑工作，并增加
必要的截屏，确保用户可以获得他们
所需要的所有上下文信息。
接下来是一轮“80%”反馈。此时，技
术上的细节也要阐释清楚，因此，反
馈的目标是，确保文档引入注目、易
于阅读，并且恰当地阐释了如何完成
相关的用户故事。
我们从这个过程中学
到了什么
自2012年开始，我们已经学到了多个
重要的教训。
小处着手。将新的小项目作为开始
改变的机会。
如果你有东西可以展示， 那么就更
容易说服别人跟随你。早在2012年，
我们就完成了第一个文档项目，我们
可以展示一些积极的结果，但无法建
立能够促使我们作出改变的意识。
不要等到重大项目开始改变。在完
成了应用程序生命周期管理工具的文
档后，我一直希望有个机会重修我们
最常用的文档——我们的IDE文档。
但总有事情妨碍。因此，如果你真得
想要改变，那么现在就从你正在交付
的新特性开始。然后，你所做的改变
将会获得一些曝光，改革过程会加
速，而其它妨碍你作出改变的事情似
乎不那么重要了。
需要有人引导改革过程。如果你对
什么感到失望，不要抱怨，做点什
么。
就个人而言，以下几个方面会让我感
到失望：
文档没有显示出OutSystems平台如
何强大和易用；
文档没有帮助用户将系统中的各
个点联系起来；
不断增长的文档维护待办事项列
表阻碍我们进行战略层面的思
考。
我看到用户故事如何帮助解决所有这
些问题，因此，我使用用户故事为一
个旗舰特性编写了文档。开始的时
候，我从团队内部获得的反馈大多数
跟不一致有关。但稍后，反馈的内容
开始发生变化，现在，使用用户故事
编写文档已成常态。
用户故事让我们成为更好的开发后
援。当用户故事确定以后，你可以在
向他人反馈时摆脱直觉的干扰。
经常执行的用户故事应该易于完成，
比如，从数据库查询数据。使用不那
么频繁的用户故事可以难一点、隐蔽
一点，比如查看OutSystems平台为提
取数据而生成的SQL。
如果开发团队实现了什么东西，但却
没有相应的用户故事，那么它可能只
是“膨胀软件（bloatware）”，你的产
品没它会更好。就是这一年，我们说
服开发团队放弃了两项特性，否则，
那两项特性会包含在产品中，但我们
99%的客户都不会用到它们。
这只是开始
到目前为止，我们创建用户故事驱动
文档的经验仅仅局限于我们产品中相
对比较直观的部分。我们还有许多东
西需要反复学习。
也许，可以使用同样的方法为框架、
API或者开发工具的其它底层特性编
写文档。或者，用户故事文档可能根
本就不能用于这些情况。
也许，有比用户故事更好的东西，但
我们尚未发现。
关于作者
Joao Fe rnande s是OutSystems的一名
研究院工程师，负责创建产品文档及
进行免费在线培训。他的终极目标
是，通过与开发团队的紧密合作，帮
助创建不需要培训或文档的产品，从
而让自己无需进行文档编写工作。
查看英文原文: User Story Driven
Docs
原文出
处：http://www.infoq.com/cn/news/
2
009/08/agile-documentation
敏捷宣言提出：“可以工作的软件胜
过面面俱到的文档”。这使得很多团
队认为敏捷项目中不需要有文档。敏
捷评论家们纷纷把有限的文档看作敏
捷方法学的弱点。Ron Jeffries提出，
敏捷并非推崇不需要文档或很少的文
档，而是强调适当的文档化。他提
到，
大家对于XP的那个最普遍的质疑
其实并不正确。他们认为我们觉
得文档化是个坏主意。而XP其实
致力于将对话的效率最大化。我
们关于文档化的建议正是由此而
来的。
如出一辙，Eelco Gravendeel也提出敏
捷中就只有两种文档，
为了保证项目运行，所有团队成
员都觉得有需要的文档 ——在理
想情况下，团队在同一个地方一
起工作，所有的知识可以通过直
接交流得到共享和传播。然而，
如果是分布式的团队，知识就不
得不通过文档进行传播了，附带
一些的影音媒介应该更有效。这
时团队至少需要有一套共同的文
档规范，来保证大家都说“普通
话”，能有相同的理解。
Eelco建议：需要多留意许多用于产
品立项的文档，因为项目一结束它们
就没用了；也就是说，
一旦你承认，这些文档仅仅是为
了符合产品立项流程而写的，当
项目结束或产品发布以后，它们
就没用了，那么，理所当然地，
对那些主张你把文档做全并保证
1
00%正确的声音，你就可以开始
说不了！这就是为何写文档是项
旷日持久（而且昂贵！）的工作
的原因。一旦你认识到这一点，
其实只需要写 到刚刚够用，能传
话、起到备忘作用就好了，你也
会理解形式也不那么重要了：写
在纸上、给白板上的图拍个照、
茶杯垫后面的草稿、story board等
都行。
最终产品的附带文档 ——这是一
些和客户事先定好的、作为产品
一部分发布的文档。比较典型的
例子包括
1
2
3
4
. 用户手册
. 发布手册
. 维护手册（用于操作软件）
. 技术文档（用于维护代码）等。
对这些文档，Eelco甚至还建议到：
尽管已经确定哪些文档需要附在
产品中，你还是可以在文档的形
式上做一些创新。你可以写个冗
长的用户手册，抑或用更多2.0的
技术，像屏幕投影（screen
casting），来做文档。后者通常比
较便宜（据统计大概便宜10
倍！），而且可能实际上更加实
用。
因此，敏捷中就需要两种文档，一种
是对团队有帮助的，另一种是要和最
终产品一起发布的。如果一个敏捷团
队正在准备一些超出这两类的文档，
那就需要多留意一下了。大多时候，
团队可以避免做这些文档。
查看英文原文： Two Types of Agile
Documents - No More, No Less!
原文出
处：http://www.infoq.com/cn/article
s/roadmap-agile-documentation
介绍一下我的朋友Jane和John。
John是一家大型公司的长期分析师，
负责捕获新的软件产品及现有软件产
品的需求。他用SRS（软件需求规格
说明书）记录所有客户对正在开发或
维护的特定产品的需求。
Jane是同一家公司的开发人员。她通
常接收John的软件需求规格说明书
（SRS），而后开始对要实现的内容
进行技术分析和设计。完成分析之
后，她就开始写代码实现。
我的这两个朋友John和Jane的需求文
档和设计文档都需要经过审批；对于
John来讲，把需求文档发给Jane之前
需要经过审批，而对Jane来讲，则是
在开始写代码之前要经过审批。
最近，John和Jane所在的公司采用了
敏捷方法来作项目管理和软件研发，
这使得他们的工作方式发生了改变。
不需要制定大量的前期需求和设计，
需求说明书和开发都被切成了小块的
信息，摒弃了使用多年的大篇幅文
档。开发人员的开发方式也发生了变
化，鼓励像实现之前先做测试设计和
用较长的名字来命名函数等这样的做
法。
不出所料，John和Jane提出了一大堆
的问题：
如果我们无法提前知道要开发什
么，那我们怎么开始开发呢？
那些功能资料如果不记录在往常
所用的SRS中，那么记录在哪里
呢？
我们如何了解要开发的所有详细
信息？
用于未来维护的说明文档和代码
放在哪里？
如果没有写文档的阶段，那么我
们什么时候写文档呢？
在过去十年中，敏捷方法在项目管理
和软件开发中的应用经历了迅速发展
的阶段，并预计将持续地增长。在向
敏捷过渡的过程中，看似宽松的开发
方式完全不同，做事不再那么传统，
为此，世界各地的许多人都会和
John、Jane一样抛出如上同样的问
题。
当公司开始过渡到敏捷理念的过程
中，一些工作方式的差异都与文档有
关。
本文将重点讲述为什么、什么时候、
如何以及在哪里编制技术和功能文
档。
真的需要文档吗？-为什么需要文
档
文档编制与敏捷理念
敏捷宣言中宣称的价值观是：
个体和互动 高于 流程和工具
工作的软件 高于 详尽的文档
客户合作 高于 合同谈判
响应变化 高于 遵循计划
尽管提到了文档，但敏捷原则在如何
编制文档方面并没有给出任何刚性的
指导原则。
因此，在敏捷管理的项目中我们应该
期待产出什么样的文档呢？
敏捷理念背后的原则是，强调为客户
实现价值。这就意味着我们应该把产
品开发的时间花在能够为客户带来价
值的那部分，避免在几乎没有什么价
值的任务上浪费时间。该原则也同样
适用于文档的编制。
在传统的瀑布方式中，文档是一个预
定义的阶段，它需要花费大量的时
间。过渡到敏捷则意味着我们必须重
新思考编写文档的方式，以避免把时
间浪费在价值具有争议的交付成果
上。
这是否意味着我们不需要编制任何文
档呢？其实不是这样的。
另一个敏捷原则是适应变化。那就意
味着我们不能提前做太多的计划，因
为事情在项目进行中会有所变化。所
以，我们永远专注的是适时的计划。
这一条也同样适用于文档。为了避免
浪费时间，我们应该只在需要文档时
才去编写它。
但是，我们如何知道它何时需要呢？
真的需要文档吗？-为
什么需要文档
如果你来自瀑布的领域，那么很自然
就会带过来定义大量文档的习惯，但
这样会导致：
编写了很多不必要的详细信息。
编写的是传统的规格说明书，敏
捷只是一个名字而已。
为了避免这个情况，有一些指导方针
帮助我们决定是否真的需要编制文
档。
为避免在文档上浪费时间，向每个相
关的人问如下问题：
这个文档是用来做什么？是支持
开发吗？还是提供功能的参考文
献？
文档的目标受众是谁？什么人？
哪个部门的？他是客户吗？或者
是未来的维护团队？
这些目标受众如何使用这篇文
档？是一个参考文献吗？还是一
个手册？
编制这些文档需要多少成本？需
要多少时间？由谁来完成？
决定是否需要文档的一个关键因素
是，只定义正好够用的文档。在干系
人真正需要的和完整的内容之间寻找
平衡点。不多不少，恰到好处。
何时，在哪，编制什
么文档
对为什么编制文档和编制多少文档达
成共识之后，在开始编制之前还需要
定义要编制什么样的文档。
什么样的文档
根据文档的目标受众来编制相应的文
档。教程？培训材料？维护支持文
档？业务规则文档？还是系统描述文
档？
在项目的每一阶段规定需要什么样的
技术文档和功能文档，从而来确定编
制什么文档：
在项目开始之前，需要什么样的
文档？
在项目中期 ，需要什么样的文
档？
在产品开发完毕或者产品推出
后，需要什么样的文档？
在哪
在一个易于访问的并可不断更新的资
源库中保存文档对保持文档的可用性
非常有帮助。用Word文档或类似的格
式会让其变得陈旧或过时。
随着项目的滚动进行，文档应当长期
保持更新，保持文档对目标受众的有
效性。
何时
不像在瀑布式开发所期待的那样，在
敏捷开发中没有文档阶段。
因此，当功能以增量的方式开发时，
文档的编制也应该是增量的，与产品
开发一起演进。
如何编制文档
在这一点上我们应该决定：
编制刚好够用的文档。
编制什么文档。
文档存在哪里，如何保持有效
性。
什么时候编制文档。
在项目的每一个阶段如何编制文档
呢，现在让我来提供一些建议和最佳
实践。
项目启动文档
在项目初期阶段，只需要少量的文
档，因为真正的工作就是如何开始。
当开始编制技术文档时，定义你选定
的两个或者三个高层次的架构图，并
定义解决方案中需要实现的高层次组
件。
在功能方面，用史诗（Epics）来定
义产品需要开发的主要特征就可以
了。
因为要用敏捷的方式管理项目，不要
求预先设计，所以在这个阶段，定义
够用的信息，让团队开始工作就足够
了。
项目文档
在项目进行阶段，随着产品的增量开
发，可能需要编制两种类型的文档：
A**．**恰到好处的需求文档-作为产
品待办事项列表（Product Backlog）
的输入。
B**．要实现的**系统和业务逻辑-作
为每个迭代的输出。
每一种文档都有它自己的目标受众：
目标受众**A: **团队。
目标受众**B**：干系人和最终的维
护团队。
这些文档需要对这两类目标受众的需
求给出回应。
功能文档
用户故事是敏捷管理项目中最常用的
功能文档。用户故事汇聚了足够的信
息，告诉开发人员如何实现这些需
求，它是用下面的格式描述的：
描述：用“作为，我想要，因此我
可以”这样的形式。
验收标准：定义故事是否完成的
标准，让团队和产品负责人对此
达成一致。
在迭代计划之前，用户故事的需求描
述必须经过干系人的认可，这意味着
现在它们已经为计划的迭代做好了准
备，它们应该有可靠的信息来源（需
求），开发人员知道要实现什么。这
需要对目标受众A提供足够的信息。
当用户故事正在开发中时，团队可能
会确定新的验收标准，然会添加到用
户故事中。
记住，在敏捷中，用户故事不应该是
一小块非常详尽的需求描述，而是希
望提供什么功能实现的指导方针，这
是产品负责人和团队之间未来合作要
实现什么产品的承诺。
当用户故事开发完成并被干系人接收
之后，那么就可以认为它是已接收的
了。这个时候，用户故事需要从
Product Backlog（需要实现的一系列
功能需求描述列表）中挪到Product
Increment（在迭代及所有之前的迭代
中已完成的一系列产品代办列表）。
当用户故事以增量的方式完成时，目
标受众B所需要的文档在下图1中显
示。
技术文档
在研发阶段，开发人员需要运用一些
公认的最佳实践（作为敏捷开发方法
的一部分），例如测试驱动开发
TDD（Test-Driven Development）和
行为驱动开发BDD（Behavior-Driven
Development），以及结构良好的代
码、非技术人员可读等。这个需要提
供描述代码的技术文档。
最新的功能和技术文档
因为代码是最新的业务规则和系统实
现的最可靠来源，因此基于代码本身
是拥有有效文档的最佳方式。
活文档是实现它的一种方式。
活文档或动态文档是持续编辑和更新
的文档。活文档的概念依赖于在代码
中集成的文档，该文档是基于验收标
准，用领域专用语言（Domai n
Specific Language）来写的，例如用
于Cucumber的Gherkin。通过工具来辅
助活文档的持续构建，写在用户故事
中的验收标准作为代码的一部分已经
实现了，并且以一种可读的格式在更
新的、典型的在线地址上输出。
提供活文档机制的一些工具包
括：Cucumber，Concordion，FitNesse
Pickles，以及其他。他们都值得一
看。
项目后期文档
由于文档是随着用户故事的实现增量
编制的，在开发周期结束和产品推出
后，那些技术和功能文档应该描述了
所有的功能实现。
归纳
当决定需要编制多少文档时，很重要
一点是要定义多少文档是刚好够用的
文档。
图2描绘了本文中所推荐的用来决定
文档编制的路线图。
在确定了为什么、做什么、什么时候
做、怎么做之后，就要用敏捷的方式
定义编制文档的最佳实践，用敏捷软
件开发的技术和活文档。
表格1中列出了每一阶段推荐的文档
输出内容。
项目
后期
选 项目前
项 期文档
项目中
期文档
（
维
护）
文档
结构良好
的代码，
无技术基
础人员易
读
测试驱动
开发
选择的
两个或
三个高
层次架
构图
代码
作为
技术
文档
技
术
（TDD）
行为驱动
开发
（BDD）
以代码为
文档
【一次一
个用户故
事】
具有定义
良好的用
户故事，
清晰的验 代码
收标准 作为
以验收标 活文
主要的
史诗定
义产品
需要开
功
能
发的主
要特征
准为文档
【一次一
个用户故
事】
档
总结
如同我的两个虚拟朋友Jane和John所
经历的一样，对任何的团队来说从传
统的瀑布式到敏捷开发的过渡都是一
种挑战。人们的工作方式已经沿用了
几十年，当发生转变时，就会引发各
种问题和质疑。
在所有这些由团队协作方式的转变
（尤其是在思想意识上的转变）而引
起的问题和质疑中，文档是一个主要
的问题，这是其中变化最大的一个--
从开发之前编制所有文档变成同一阶
段几乎不怎么写文档。
敏捷的基本原则并没有说不需要任何
文档，只是提醒团队应该注重给客户
交付的价值。在编制文档的过程中，
也应该考虑这一关键原则。
所以，编制文档时请记住，只在需要
的时候编制必要的文档，不多也不
少。
提醒你的团队要适时地编制恰到好处
的文档。
关于作者
在大约二十年前，Ester F. Gonçalves
作为一名开发人员和系统分析师开始
了她的职业生涯。在最近的四年里，
她决定研究IT的业务领域。她在敏捷
管理的团队中从事IT业务分析工作，
成为了一名敏捷爱好者，研究敏捷方
法论、系统和业务分析技术，撰写和
发表了多篇相关的文章和博客，偶尔
在会议和研讨会上发表这些主题的演
讲，并且渴求自己做得更好。
查看英文原
文：http://www.infoq.com/articles/road
map-agile-documentation
原文出
处：http://www.infoq.com/cn/news/
2
015/09/readme-io
那些包含着相对较新工具的文档，比
如@Asciidoctor和Cyrille Martraire的
领域驱动设计启示书《动态文档》，
是软件开发过程中被忽略的最大领域
之一，如今终于得到了大家的些许关
注。对于一个API文档来说，其被认
为是至关重要的。Gregory Koberger
正在开发一套系统，可以让开发者文
档与API和API仪表盘更直接地对接。
最近InfoQ采访了Readme.io的首席执
行官Gregory，为了实现他对于API文
档的愿景，其创建了这家公司。
InfoQ**：您能描述一下创建
Re adme .io背后的故事吗，以及它是
如何演化的？**
Gre gory Kobe rge r**：**当然可
以，首先我是一名程序员及设计
师，并且对开发工具感兴趣，因
为在那片领域有着一套独特的设
计挑战魅力。
我曾经花费了大量的时间用来写
作和阅读文档，但是我认为应该
有更好的方式实现它。大约五年
前，我下定决心我要潜心专研这
片领域，但是刚开始的时候我度
过了一段艰难的时期。谢天谢地
的是，像Stripe和Twilio这样的公
司已经向人们展示了文档的重要
性。大约一年前，我们成立了这
家公司。
公司运行的非常好。我们也确实
发现，一份更优秀的文档能够在
某些产品和问题上发挥好的作
用。我们正走向希望人们开始改
变对文档的原有看法这一步。它
不应该是一成不变的。它应该随
着阅读它的群体和阅读群体的知
识量而改变。
InfoQ**：您对Re adme .io的愿景是什
么？**
GK**：**API由三部分组成：文
档、仪表板（用来生成开发者密
匙等）和API本身。
我想着手把它们整合到一起。API
了解代码和数据。仪表板了解用
户。文档习惯上仍是一成不变，
对它们一无所知。
比如，想象一下，如果文档知道
用户语言，并且可以直接显示代
码片段，或者想象如果文档知道
用户犯了某个具体的错误，并能
够帮他解决这个错误。
InfoQ**：当需要记录API时，您的
API团队主要面临的挑战是什么？**
GK**：**一个大问题是,记录API
文档不是一个优先事项。人们包
括我自己都非常不善于记录某个
API。很难回到从前，猜测新人在
使用你的API时需要了解哪些东
西。并且很难永远保持文档是最
新可用的。
InfoQ**：Re adme .io是如何帮助人们
的？它的主要特点有哪些？**
GK**：**目前，我们主要专注于
文档。就像WordPress专注于代码
和API一样。我们让您在为客户提
供开发体验时变得更加容易。
Readme已经能够支持表单、登录
页面、教程等等。我们让人们在
在网页上正确地使用API，进行变
更，允许他们看看会发生什么。
我们同样能够从GitHub上自动同步
API文档并友好的展示出来。
InfoQ**：Re adme .io与其它开源替代
方案相比如何，比如Swagger UI
或Slate？**
GK**：**Readme.io有一个优势是
公司的所有人都可以参与其中，
不仅仅是开发者。很快我们将支
持Swagger，这样我们就可以替换
Swagger UI。同样我们认为，社区
也应该参与到文档的记录过程
中。因此，我们有一些建议性的
编辑器：公司内部或者外部人员
可以通过一个友好的拖放编辑器
提交更改意见。
InfoQ**：Re adme .io创建的文档可以
部署到某个现有的开发者门户网站
吗？**
GK**：**我们的目标是成为一个
开发者中心。目前，你可以在一
个现有的中心使用它。在未来，
我们希望将文档，仪表板和支持
整合到一块。当它们都在同一个
地方时，它们真的会一起运行的
很好。
InfoQ**：你们支持API定义语言吗？
比如Swagger，RAML和API
Blue print。**
GK**：**是的。目前我们用一种
叫做APIdoc的东西。不久我们将
Blueprint的支持。
与编写段落文本相比，通过语义
上记录你的API，你可以创造更多
的价值。因为你可以着手给用户
定制生成SDKs或者代码示例。
现在，我们仅限于导入这些语
言，但是，我们认为让人们导出
语言同样的重要。Readme.io很幸
运能够站在开发体验中心的舞台
上，我们真的想利用这次机会成
为不同API公司的交流中心。
InfoQ**：你们是如何支持各种API开
发工作流的，是代码优先还是API优
先？**
GK**：**通常，API仅仅是以复制
主网站构建的方式编写。那是一
个很糟糕的事情，因为很多时
候，你用API做一些网站不能做的
事情。
所以，我认为将API看做网站的一
个独立的实体是很重要的，因为
你希望它足够的灵活，能够做一
些网站不能做的事情。
InfoQ**：您认为哪种方式能最好的
描述API，并且能够与其实现的演化
相同步？**
GK**：**现在有很多种方法可以
描述API，比如Swagger，RAML和
API Blueprint。我们选择APIdoc，
是因为这种文档非常接近代码本
身。它类似于Javadoc，这种文档
是对代码的一种注释，而不是一
个单独的文件。我们可以从GitHub
上自动同步。
InfoQ**：在一个典型的API团队中，
谁应该负责记录API？**
GK**：**每一个人都应该。习惯
上来讲，只有开发者做记录。但
是，API对业务、市场营销和产品
管理团队同样非常重要。我们希
望实现每个人从开发者到CEO都能
够更新与他们相关联的文档。
我们认为社区对记录文档拥有难
以置信的重要意义，因为他们有
其他人所没有的疑问和用例。
InfoQ**：从您的观点来看，API文档
和操作的API管理是否应该分开处
理？**
GK**：**我真的很喜欢这个API的
生态系统。现在有很多公司在做
具体事情，并且做的很好。而对
于较大的API管理公司，什么事都
想自己做 但大部分做的很差。
我认为API管理和文档应该分开，
但是，它们应该被更紧密的集成
起来。
InfoQ**：请问Re adme .io下一版本的
推出时间和新功能有哪些？**
GK**：**我们正在做一个重大的
重新设计工作，大约需要一个月
左右的时间。除了看上去更加美
观，我们将为参考指南和示例设
置单独的版块。
对于文档编写人员，事情的发展
和文档中应该包含哪些内容变的
更加明显。对于终端用户，将会
更容易知道从哪里获取他们想要
的信息。
因为我们想着手自动化记录您API
更多的过程，所以像Swagger导入
之类的事变的非常重要。
大部分开发人员都要花费时间阅
读或者编写文档。它是我们与代
码库或API进行交互的界面，而且
我真的很高兴Readme正变的有能
力改变人们以往的方式。
你可以尝试免费版的Readme.io，并
且它保留了免费的开源项目。对于专
属软件，企业在Readme.io子领域提
供了一个基本包，包括3个文档版本
和一个管理员用户，花费$14/月。开
发者中心版本允许您使用自己的域
名，并且支持10个管理员用户，花费
$59 /月。
查看英文原文： Interview with
Readme.io Founder on the Future of API
Documentation
