> 原文出处：http://www.infoq.com/cn/articles/story-driven-docs 在OutSystems，我们创建了一个平台，旨在简化应用程序整个生命周期的管理流程。但是，对于用户而言，我们的文档却不简单。 我们的文档侧重于描述UI（用户界面）提供的每个按钮，而不是用户的意图和目的。 一个明显的例子是，对于文本查找功能（CTRL+F），我们有一整页的文档。这页文档详细描述了UI提供的每一种选项，其详细程度令人难以忍受： * 区分大小写、不区分大小写 * 全词匹配 * 细化搜索范围 我们专注于这些不言自明的选项，但却没有告诉用户如何找到他们需要的东西： * 如何找出所有具有给定名称的元素； * 如何找出所有影响标题的CSS规则； * 如何找出所有针对特定数据库表的查询。 对我们而言，维护文档非常困难。OutSystems平台不断变化，我们跟不上它的节奏。 更重要的是，我们没有满足用户的需求。这从个位数的页面访问量和我们从部分客户那里得到的反馈很容易看出来。 在本文中，我将讨论如何停止编写UI文档，并开始提供用户故事驱动的文档。 现在，我们专注于用户想要实现什么以及他们可以如何实现，这与他们需要用到多少窗口或按钮无关。我们还可以更好地排定工作优先级，那样一来，最常用的用户故事会获得更多的关注和资源。 我将讨论以下几个方面的内容： * 为什么要避免编写UI文档； * 如何检查你当前是否是在编写UI文档； * 为什么用户故事是一种更好的产品文档编写方式； * 专注于用户故事如何改变了我们团队的文化，使我们可以从事真正重要的工作。 那么让我们开始吧。 [TOC=2] ## 为什么要避免编写UI文档 编写UI文档可能使用户更难以理解你的产品，这显而易见。这样做也可能不利于你和你的团队，但这就不是那么容易理解了。 所以，我们首先重点讨论下对用户的影响，然后再探讨下给你和你的团队带来的一些后果。 如果你编写的是UI文档，即使用户找到了正确的文档，他们也无法获得完成一项任务所需的所有上下文。 这对于新用户和专家用户而言都会带来困难： * **新用户**——他们无法理解概念之间的关联关系以及如何搭配使用现有工具解决问题； * **专家用户**——他们会在查找参考文档方面遇到困难，因此，他们需要诉诸于试验。  ## 新用户的日子会不好过 使用CRTL+F查找什么东西非常简单，但是大多数任务，比如查询数据库表，需要了解若干概念以及它们彼此之间的关联关系。 因此，对于首次接触的新用户而言，即使是简单的任务，看上去也会很难。以我们的文档为例，我们有大约13页文档解释如何查询一张数据库表。即使新用户非常有耐心，并且读完了所有的文档，他们还是会很难理解如何获取数据。  更重要的是，他们很难理解如何搭配使用所需的工具在页面上展示查询结果。 虽然OutSystems有一个可视化的开发环境，但这还是很让我失望。这是因为，查询数据并展示在页面上只需三次拖放外加两次鼠标点击。唉，采用复杂的方式来做，才会这么麻烦。否则，一次拖放就够了。  ## 专家用户的日子会不好过 专家用户的日子也不会轻松。当集中注意力编写UI文档时，你很难将需要组织到用户指南中的信息和应该作为参考的信息区分开。在你看来，所有东西都像参考。 最终，你会将所有的东西都混在一起，即使是经验丰富的用户，要找到他们正在查找的详细说明，也变得更加困难。 ## 搜索引擎很难将流量导向文档 即使你编写的文档适合新用户及专家用户，如果用户无法找到你的文档，那么你所有的努力也都会白费。 因为当你编写UI文档时，文档的内容和标题反映的是： * 你命名的功能名称； * 窗口的标题或名称； * 按钮标签。 对SEO（搜索引擎优化）而言，那可能不是最好的选择。 以我们为例，我们将查找功能的文档页命名为“Find Tool”。这个名字仅仅描述了用户能够从界面上看到的东西。因此，对于用户而言，这一页几乎没什么价值。 对于其它的文档页，情况也没多好。由于内容与用户需求不匹配，所以它最终也没有包含用户查找的关键词。因为当你集中注意力编写UI文档时，文档中不会包含用户查找的关键词，所以文档在搜索引擎中的排名不够高，用户无法找到。 如果没有一个好的页面标题，即使文档排名更高也可能没用。搜索引擎会将页面标题作为搜索结果的一部分显示。如果页面标题与用户的心理模型不匹配，那么他们可能不会点击那个可以将他们导向文档的链接。 ## 你和你的团队的日子也会不好过 当你编写UI文档时，每个任务、窗口和按钮对你而言都同等重要。 当所有东西的重要性都相同时，就很难排定工作优先级。这很危险，尤其是当你正奔向里程碑时。作为一个副作用，你将会很为难地接受这样的现实，就是可以不为那些对系统运行而言微不足道的任务编写文档。 功能稍有变化（比如按钮标签或在界面中的位置稍稍改变），你就会想马上更新文档。我不是主张你应该放着文档不管。但对我们而言，这意味着一个永不完结的文档维护待办事项列表。 整个方法让团队很难做战略层面的思考。很快，你就会将更多的精力放在内部流程中，努力缩短文档维护待办事项列表，而不是致力于对于用户而言重要的东西。 ## 如何检查你是否正在编写UI文档 关键的问题是没有客户或涉众能够直接告诉你你正在编写UI文档。假如有什么没能发挥作用，这会让你更难以准确地找到解决问题的方法。 但从我们的经验来看，下面一些迹象可能可以说明你正在编写UI文档： * 你的客户抱怨，他们无法将系统中的各个点联系起来，或者对于如何协调多个可用的工具没有一个总览视图； * 文档的每一部分都像是参考； * 许多文档页描述了相同但稍有变化的内容； * 部分页面的页面访问量或平均阅读次数一直很少，而对于如何做出改变，你没有一点头绪； * 你有一个很长的文档维护待办事项列表，妨碍了你做战略层面的思考。 上述所有症状我们都有，但却不知道做什么才能解决它们。我们认为，所有这些问题都是孤立的，每个问题可以使用单独的方案来解决。 ## 我们如何开始做出改变 从发现我们正在编写UI文档，到弄清楚我们能够做什么，是一段很长的路。下面，我将简单介绍一下我们努力改变OutSystems平台文档编写流程和方式的过程。 ### 2012年5月 大约在2012年5月，作为OutSystems平台的一部分，我们推出了一款新的生命周期管理工具。但这次，我们采用了一种不同的理念来处理这个文档项目。 我们与开发团队、产品经理、支持人员坐在一起，收集这个工具处理的用户故事。我们识别出了大约18个用户故事，但只有12个是关键的。其它6个要么由主用户故事稍做变化得来，要么是工具未能很好处理的边缘情况。 我们开始注意到，对于这个项目，排定优先级并不容易。由于用户故事构建在其它用户故事的基础上，我们处理事情的顺序很自然地就确定了。随着最后期限越来越近，我们开始倾向于推迟低优先级的用户故事。如果有更重要的问题需要处理，那么我们可以在产品发布之后交付剩余的文档。 另外，我们还倾向于压根不编写文档，而是等待用户的反馈。 然后，我们有点退步。我们团队内部发生了一些变化，我们开始设计一个新的在线培训。这是一个大项目，我们需要将大部分资源都投入进去。因此，在那段时间里，我们无法对文档做重大修改。 ### 2014年5月 我们正向着下一个主要版本迈进。短暂的失望过后，我们看到可以提供更好的文档，我与我们的团队分享了一些我认为令人赞叹的文档项目。 我向他们展示，我们可以做得更好，我们只需要投入精力去做。 但我知道，要改变我们交付文档的方式，这还不够。因此，我还向团队展示了，我是如何为我们推出的其中一项主要功能编写几乎所有的文档。我编写的文档中只有用户故事，我并没有试图编写UI文档。 通过宣传推动，大家一致同意在为其它旗舰特性编写文档时使用用户故事。但我们没有创建任何流程或风格指南来确保我们都交付用户故事。因此，对于部分较小的特性，其文档中混合了用户故事和UI。 ### 2014年10月 我们发布了从5月份就开始编写的文档版本，我们都累坏了。 我们决定停下来，做一个团队回顾。每个团队成员准备一段20分钟的演讲，内容是关于他们在该版本发布之前的6个月里所参与的项目。对于每个项目，每个团队成员还需要指出三件进展顺利的事以及三个还能改进的地方。 我写过一篇[文章](http://www.joaofn.com/post/outsystems-platform-a-retrospective/)，详细介绍那次回顾，但总体上我们认为，使用用户故事让我们： * 能够在到达Beta里程碑之前交付文档； * 现有的文档得到明显改善； * 更具生产力，因为更容易排定工作优先级了。 另外，总的来说，专注于用户故事还使我们团队同开发团队之间的讨论更专注、更简单。 我们只是需要结构化我们处理项目的方式，因为每个团队成员都有自己的流程。结构化将使项目管理更简单，使我们可以在将来的项目中节省时间。 ## 我们现在的文档编写流程 那次回顾之后，我们一致同意使用下面的五步流程进行迭代： * 及早开始，经常对开发团队进行随访； * 检查是否是开始创建文档和培训材料的恰当时机； * 动手测试新特性； * 编写文档草稿，并要求涉众反馈； * 如果需要，进一步修饰文档并要求反馈。  ## 及早开始并经常随访 在OutSystems，开发团队会在项目开始前主持召开一个项目启动会议。每个团队都会邀请我们及其它涉众，因此，我们知道每个团队正在做什么。 然后，我们会分析团队收集的用户故事，并查看他们创建的设计文档。如果我们对一个用户故事有不同意见，那么我们会同开发团队和产品管理部门一起评审，确保我们只提供最重要的用户故事。 ## 找出开始编写文档的恰当时机 由于大多数团队都混合使用SCRUM和看板，所以他们还会在每个冲刺之后演示新进展。这些接触点使我们可以评估团队有多大进展，并检查下，开始为新特性编写文档及培训材料是否合适。 时机必须恰当。如果介入过早，那么我们会为容易变化的特性编写文档。如果介入太晚，那么我们就有延期交付文档的风险。更重要的是，我们会冒着无法向开发团队提供反馈的风险，而他们可能会为用户创建特性。 ## 测试新特性并反馈 当我们认为时机恰当时，我们从开发团队那里获取一个构建版本，并尝试针对新特性执行用户故事。 我们实现了一些概念验证，只是为了通过尝试找出在文档中讲故事的最佳方式。例如，关于从数据库提取数据的文档是否应该关注提取客户、订单、票据或其它信息？ 在积累了一些新特性的使用经验后，我们还会同开发团队分享我们的反馈。我们可以借此准确地指出什么情况让新特性难以学习和使用。例如，认识到从多个表查询数据的方式并不直观，了解到某个特定属性的用途，或者一条错误消息试图传达的信息。 ## 创建文档草稿 然后，我们开始为新特性编写文档草稿。通常，我们会协同使用多种编辑工具，如Google文档，并避免使用标记、截屏或其它任何让我们从试图阐释的用户故事分心的东西。 接下来，在我们团队和实现特性的开发团队内部将展开一轮“20%”反馈。这轮反馈的目标是，确认用户故事和我们用于阐释用户故事的示例是否明确。 ## 修饰文档 最后，在我们都认为用户故事合理、叙事良好之后，我们会评审和修饰文档。我们会做一些编辑工作，并增加必要的截屏，确保用户可以获得他们所需要的所有上下文信息。 接下来是一轮“80%”反馈。此时，技术上的细节也要阐释清楚，因此，反馈的目标是，确保文档引入注目、易于阅读，并且恰当地阐释了如何完成相关的用户故事。 ## 我们从这个过程中学到了什么 自2012年开始，我们已经学到了多个重要的教训。 **小处着手**。将新的小项目作为开始改变的机会。  如果你有东西可以展示， 那么就更容易说服别人跟随你。早在2012年，我们就完成了第一个文档项目，我们可以展示一些积极的结果，但无法建立能够促使我们作出改变的意识。 **不要等到重大项目开始改变**。在完成了应用程序生命周期管理工具的文档后，我一直希望有个机会重修我们最常用的文档——我们的IDE文档。但总有事情妨碍。因此，如果你真得想要改变，那么现在就从你正在交付的新特性开始。然后，你所做的改变将会获得一些曝光，改革过程会加速，而其它妨碍你作出改变的事情似乎不那么重要了。 **需要有人引导改革过程**。如果你对什么感到失望，不要抱怨，做点什么。  就个人而言，以下几个方面会让我感到失望： * 文档没有显示出OutSystems平台如何强大和易用； * 文档没有帮助用户将系统中的各个点联系起来； * 不断增长的文档维护待办事项列表阻碍我们进行战略层面的思考。 我看到用户故事如何帮助解决所有这些问题，因此，我使用用户故事为一个旗舰特性编写了文档。开始的时候，我从团队内部获得的反馈大多数跟不一致有关。但稍后，反馈的内容开始发生变化，现在，使用用户故事编写文档已成常态。 **用户故事让我们成为更好的开发后援**。当用户故事确定以后，你可以在向他人反馈时摆脱直觉的干扰。 经常执行的用户故事应该易于完成，比如，从数据库查询数据。使用不那么频繁的用户故事可以难一点、隐蔽一点，比如查看OutSystems平台为提取数据而生成的SQL。 如果开发团队实现了什么东西，但却没有相应的用户故事，那么它可能只是“膨胀软件（bloatware）”，你的产品没它会更好。就是这一年，我们说服开发团队放弃了两项特性，否则，那两项特性会包含在产品中，但我们99%的客户都不会用到它们。 ## 这只是开始 到目前为止，我们创建用户故事驱动文档的经验仅仅局限于我们产品中相对比较直观的部分。我们还有许多东西需要反复学习。 也许，可以使用同样的方法为框架、API或者开发工具的其它底层特性编写文档。或者，用户故事文档可能根本就不能用于这些情况。 也许，有比用户故事更好的东西，但我们尚未发现。 ## 关于作者  **[Joao Fernandes](http://www.joaofn.com/)**是OutSystems的一名研究院工程师，负责创建产品文档及进行免费在线培训。他的终极目标是，通过与开发团队的紧密合作，帮助创建不需要培训或文档的产品，从而让自己无需进行文档编写工作。 **查看英文原文:**[User Story Driven Docs](http://http//www.infoq.com/articles/story-driven-docs)