> 原文出处：http://www.infoq.com/cn/news/2015/09/readme-io 那些包含着相对较新工具的文档，比如@Asciidoctor和Cyrille Martraire的领域驱动设计启示书《动态文档》，是软件开发过程中被忽略的最大领域之一，如今终于得到了大家的些许关注。对于一个API文档来说，其被认为是至关重要的。Gregory Koberger正在开发一套系统，可以让开发者文档与API和API仪表盘更直接地对接。 最近InfoQ采访了[Readme.io](https://readme.io/)的首席执行官Gregory，为了实现他对于API文档的愿景，其创建了这家公司。 **InfoQ****：您能描述一下创建****Readme.io****背后的故事吗，以及它是如何演化的？** > **Gregory Koberger****：**当然可以，首先我是一名程序员及设计师，并且对开发工具感兴趣，因为在那片领域有着一套独特的设计挑战魅力。 > > 我曾经花费了大量的时间用来写作和阅读文档，但是我认为应该有更好的方式实现它。大约五年前，我下定决心我要潜心专研这片领域，但是刚开始的时候我度过了一段艰难的时期。谢天谢地的是，像Stripe和Twilio这样的公司已经向人们展示了文档的重要性。大约一年前，我们成立了这家公司。 > > 公司运行的非常好。我们也确实发现，一份更优秀的文档能够在某些产品和问题上发挥好的作用。我们正走向希望人们开始改变对文档的原有看法这一步。它不应该是一成不变的。它应该随着阅读它的群体和阅读群体的知识量而改变。 **InfoQ****：您对****Readme.io****的愿景是什么？** > **GK****：**API由三部分组成：文档、仪表板（用来生成开发者密匙等）和API本身。 > > 我想着手把它们整合到一起。API了解代码和数据。仪表板了解用户。文档习惯上仍是一成不变，对它们一无所知。 > > 比如，想象一下，如果文档知道用户语言，并且可以直接显示代码片段，或者想象如果文档知道用户犯了某个具体的错误，并能够帮他解决这个错误。 **InfoQ****：当需要记录****API****时，您的****API****团队主要面临的挑战是什么？** > **GK****：**一个大问题是,记录API文档不是一个优先事项。人们包括我自己都非常不善于记录某个API。很难回到从前，猜测新人在使用你的API时需要了解哪些东西。并且很难永远保持文档是最新可用的。 **InfoQ****：****Readme.io****是如何帮助人们的？它的主要特点有哪些？** > **GK****：**目前，我们主要专注于文档。就像WordPress专注于代码和API一样。我们让您在为客户提供开发体验时变得更加容易。 > > Readme已经能够支持表单、登录页面、教程等等。我们让人们在在网页上正确地使用API，进行变更，允许他们看看会发生什么。我们同样能够从GitHub上自动同步API文档并友好的展示出来。 **InfoQ****：****Readme.io****与其它开源替代方案相比如何，比如****Swagger UI****或****Slate****？** > **GK****：**Readme.io有一个优势是公司的所有人都可以参与其中，不仅仅是开发者。很快我们将支持Swagger，这样我们就可以替换Swagger UI。同样我们认为，社区也应该参与到文档的记录过程中。因此，我们有一些建议性的编辑器：公司内部或者外部人员可以通过一个友好的拖放编辑器提交更改意见。 **InfoQ****：****Readme.io****创建的文档可以部署到某个现有的开发者门户网站吗？** > **GK****：**我们的目标是成为一个开发者中心。目前，你可以在一个现有的中心使用它。在未来，我们希望将文档，仪表板和支持整合到一块。当它们都在同一个地方时，它们真的会一起运行的很好。 **InfoQ****：你们支持****API****定义语言吗？比如****Swagger****，****RAML****和****API Blueprint****。** > **GK****：**是的。目前我们用一种叫做[APIdoc](https://readme.io/)的东西。不久我们将会发布对[Swagger](http://swagger.io/)，[RAML](http://raml.org/)和[API Blueprint](https://apiblueprint.org/)的支持。 > > 与编写段落文本相比，通过语义上记录你的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****：请问****Readme.io****下一版本的推出时间和新功能有哪些？** > **GK****：**我们正在做一个重大的重新设计工作，大约需要一个月左右的时间。除了看上去更加美观，我们将为参考指南和示例设置单独的版块。 > > 对于文档编写人员，事情的发展和文档中应该包含哪些内容变的更加明显。对于终端用户，将会更容易知道从哪里获取他们想要的信息。 > > 因为我们想着手自动化记录您API更多的过程，所以像Swagger导入之类的事变的非常重要。 > > 大部分开发人员都要花费时间阅读或者编写文档。它是我们与代码库或API进行交互的界面，而且我真的很高兴Readme正变的有能力改变人们以往的方式。 你可以尝试免费版的[Readme.io](http://readme.io/)，并且它保留了免费的开源项目。对于专属软件，企业在Readme.io子领域提供了一个基本包，包括3个文档版本和一个管理员用户，花费$14/月。开发者中心版本允许您使用自己的域名，并且支持10个管理员用户，花费$59 /月。 **查看英文原文：**[Interview with Readme.io Founder on the Future of API Documentation](http://www.infoq.com/news/2015/08/readme-io)

> 原文出处：http://www.infoq.com/cn/articles/roadmap-agile-documentation 介绍一下我的朋友Jane和John。 John是一家大型公司的长期分析师，负责捕获新的软件产品及现有软件产品的需求。他用SRS（软件需求规格说明书）记录所有客户对正在开发或维护的特定产品的需求。 Jane是同一家公司的开发人员。她通常接收John的软件需求规格说明书（SRS），而后开始对要实现的内容进行技术分析和设计。完成分析之后，她就开始写代码实现。 我的这两个朋友John和Jane的需求文档和设计文档都需要经过审批；对于John来讲，把需求文档发给Jane之前需要经过审批，而对Jane来讲，则是在开始写代码之前要经过审批。 最近，John和Jane所在的公司采用了敏捷方法来作项目管理和软件研发，这使得他们的工作方式发生了改变。不需要制定大量的前期需求和设计，需求说明书和开发都被切成了小块的信息，摒弃了使用多年的大篇幅文档。开发人员的开发方式也发生了变化，鼓励像实现之前先做测试设计和用较长的名字来命名函数等这样的做法。 不出所料，John和Jane提出了一大堆的问题： * 如果我们无法提前知道要开发什么，那我们怎么开始开发呢？ * 那些功能资料如果不记录在往常所用的SRS中，那么记录在哪里呢？ * 我们如何了解要开发的所有详细信息？ * 用于未来维护的说明文档和代码放在哪里？ * 如果没有写文档的阶段，那么我们什么时候写文档呢？ 在过去十年中，敏捷方法在项目管理和软件开发中的应用经历了迅速发展的阶段，并预计将持续地增长。在向敏捷过渡的过程中，看似宽松的开发方式完全不同，做事不再那么传统，为此，世界各地的许多人都会和John、Jane一样抛出如上同样的问题。 当公司开始过渡到敏捷理念的过程中，一些工作方式的差异都与文档有关。 本文将重点讲述为什么、什么时候、如何以及在哪里编制技术和功能文档。 [TOC] ## 文档编制与敏捷理念 敏捷宣言中宣称的价值观是： 个体和互动 高于 流程和工具  工作的软件 高于 详尽的文档  客户合作 高于 合同谈判  响应变化 高于 遵循计划 尽管提到了文档，但敏捷原则在如何编制文档方面并没有给出任何刚性的指导原则。 因此，在敏捷管理的项目中我们应该期待产出什么样的文档呢？ 敏捷理念背后的原则是，强调为客户实现价值。这就意味着我们应该把产品开发的时间花在能够为客户带来价值的那部分，避免在几乎没有什么价值的任务上浪费时间。该原则也同样适用于文档的编制。 在传统的瀑布方式中，文档是一个预定义的阶段，它需要花费大量的时间。过渡到敏捷则意味着我们必须重新思考编写文档的方式，以避免把时间浪费在价值具有争议的交付成果上。 这是否意味着我们不需要编制任何文档呢？其实不是这样的。 另一个敏捷原则是适应变化。那就意味着我们不能提前做太多的计划，因为事情在项目进行中会有所变化。所以，我们永远专注的是适时的计划。这一条也同样适用于文档。为了避免浪费时间，我们应该只在需要文档时才去编写它。 但是，我们如何知道它何时需要呢？ ## 真的需要文档吗？-为什么需要文档 如果你来自瀑布的领域，那么很自然就会带过来定义大量文档的习惯，但这样会导致： * 编写了很多不必要的详细信息。 * 编写的是传统的规格说明书，敏捷只是一个名字而已。 为了避免这个情况，有一些指导方针帮助我们决定是否真的需要编制文档。 为避免在文档上浪费时间，向每个相关的人问如下问题： * 这个文档是用来做什么？是支持开发吗？还是提供功能的参考文献？ * 文档的目标受众是谁？什么人？哪个部门的？他是客户吗？或者是未来的维护团队？ * 这些目标受众如何使用这篇文档？是一个参考文献吗？还是一个手册？ * 编制这些文档需要多少成本？需要多少时间？由谁来完成？ 决定是否需要文档的一个关键因素是，只定义正好够用的文档。在干系人真正需要的和完整的内容之间寻找平衡点。不多不少，恰到好处。 ## 何时，在哪，编制什么文档 对为什么编制文档和编制多少文档达成共识之后，在开始编制之前还需要定义要编制什么样的文档。 ### 什么样的文档 根据文档的目标受众来编制相应的文档。教程？培训材料？维护支持文档？业务规则文档？还是系统描述文档？ 在项目的每一阶段规定需要什么样的技术文档和功能文档，从而来确定编制什么文档： * 在项目开始之前，需要什么样的文档？ * 在项目中期 ，需要什么样的文档？ * 在产品开发完毕或者产品推出后，需要什么样的文档？ ### 在哪 在一个易于访问的并可不断更新的资源库中保存文档对保持文档的可用性非常有帮助。用Word文档或类似的格式会让其变得陈旧或过时。 随着项目的滚动进行，文档应当长期保持更新，保持文档对目标受众的有效性。 ### 何时 不像在瀑布式开发所期待的那样，在敏捷开发中没有文档阶段。 因此，当功能以增量的方式开发时，文档的编制也应该是增量的，与产品开发一起演进。 ## 如何编制文档 在这一点上我们应该决定： * 编制刚好够用的文档。 * 编制什么文档。 * 文档存在哪里，如何保持有效性。 * 什么时候编制文档。 在项目的每一个阶段如何编制文档呢，现在让我来提供一些建议和最佳实践。 ### 项目启动文档 在项目初期阶段，只需要少量的文档，因为真正的工作就是如何开始。 当开始编制技术文档时，定义你选定的两个或者三个高层次的架构图，并定义解决方案中需要实现的高层次组件。 在功能方面，用史诗（Epics）来定义产品需要开发的主要特征就可以了。 因为要用敏捷的方式管理项目，不要求预先设计，所以在这个阶段，定义够用的信息，让团队开始工作就足够了。 ### 项目文档 在项目进行阶段，随着产品的增量开发，可能需要编制两种类型的文档： **A****．**恰到好处的需求文档-作为产品待办事项列表（Product Backlog）的输入。 **B****．要实现的**系统和业务逻辑-作为每个迭代的输出。 每一种文档都有它自己的目标受众： **目标受众****A: **团队。 **目标受众****B****：**干系人和最终的维护团队。 这些文档需要对这两类目标受众的需求给出回应。 **功能文档** 用户故事是敏捷管理项目中最常用的功能文档。用户故事汇聚了足够的信息，告诉开发人员如何实现这些需求，它是用下面的格式描述的： * 描述：用“作为，我想要，因此我可以”这样的形式。 * 验收标准：定义故事是否完成的标准，让团队和产品负责人对此达成一致。 在迭代计划之前，用户故事的需求描述必须经过干系人的认可，这意味着现在它们已经为计划的迭代做好了准备，它们应该有可靠的信息来源（需求），开发人员知道要实现什么。这需要对目标受众**A**提供足够的信息。 当用户故事正在开发中时，团队可能会确定新的验收标准，然会添加到用户故事中。 记住，在敏捷中，用户故事不应该是一小块非常详尽的需求描述，而是希望提供什么功能实现的指导方针，这是产品负责人和团队之间未来合作要实现什么产品的承诺。 当用户故事开发完成并被干系人接收之后，那么就可以认为它是已接收的了。这个时候，用户故事需要从Product Backlog（需要实现的一系列功能需求描述列表）中挪到Product Increment（在迭代及所有之前的迭代中已完成的一系列产品代办列表）。 当用户故事以增量的方式完成时，目标受众**B**所需要的文档在下图1中显示。  **技术文档** 在研发阶段，开发人员需要运用一些公认的最佳实践（作为敏捷开发方法的一部分），例如测试驱动开发TDD（Test-Driven Development）和行为驱动开发BDD（Behavior-Driven Development），以及结构良好的代码、非技术人员可读等。这个需要提供描述代码的技术文档。 **最新的功能和技术文档** 因为代码是最新的业务规则和系统实现的最可靠来源，因此基于代码本身是拥有有效文档的最佳方式。 活文档是实现它的一种方式。 活文档或动态文档是持续编辑和更新的文档。活文档的概念依赖于在代码中集成的文档，该文档是基于验收标准，用领域专用语言（Domain Specific Language）来写的，例如用于Cucumber的Gherkin。通过工具来辅助活文档的持续构建，写在用户故事中的验收标准作为代码的一部分已经实现了，并且以一种可读的格式在更新的、典型的在线地址上输出。 提供活文档机制的一些工具包括：[Cucumber](http://cukes.info/)，[Concordion](http://concordion.org/)，[FitNesse](http://www.fitnesse.org/)，[SpecFlow](http://www.specflow.org/)， [Pickles](http://www.nuget.org/packages/Pickles/)，以及其他。他们都值得一看。 ## 项目后期文档 由于文档是随着用户故事的实现增量编制的，在开发周期结束和产品推出后，那些技术和功能文档应该描述了所有的功能实现。 ## 归纳 当决定需要编制多少文档时，很重要一点是要定义多少文档是刚好够用的文档。 图2描绘了本文中所推荐的用来决定文档编制的路线图。  在确定了为什么、做什么、什么时候做、怎么做之后，就要用敏捷的方式定义编制文档的最佳实践，用敏捷软件开发的技术和活文档。 表格1中列出了每一阶段推荐的文档输出内容。 |  选项 | **项目前期文档** | **项目中期文档**| **项目后期（维护）文档**| |---|---|---|---| | **技术** | 选择的两个或三个高层次架构图 | 结构良好的代码，无技术基础人员易读<br/>测试驱动开发 （TDD）<br/>行为驱动开发 （BDD）<br/>以代码为文档<br/>【一次一个用户故事】 | 代码作为技术文档 | | **功能** | 主要的史诗定义产品需要开发的主要特征 | 具有定义良好的用户故事，清晰的验收标准<br/>以验收标准为文档<br/>【一次一个用户故事】 | 代码作为活文档 | ## 总结 如同我的两个虚拟朋友Jane和John所经历的一样，对任何的团队来说从传统的瀑布式到敏捷开发的过渡都是一种挑战。人们的工作方式已经沿用了几十年，当发生转变时，就会引发各种问题和质疑。 在所有这些由团队协作方式的转变（尤其是在思想意识上的转变）而引起的问题和质疑中，文档是一个主要的问题，这是其中变化最大的一个--从开发之前编制所有文档变成同一阶段几乎不怎么写文档。 敏捷的基本原则并没有说不需要任何文档，只是提醒团队应该注重给客户交付的价值。在编制文档的过程中，也应该考虑这一关键原则。 所以，编制文档时请记住，只在需要的时候编制必要的文档，不多也不少。 提醒你的团队要适时地编制恰到好处的文档。 ## 关于作者  在大约二十年前，**Ester F. Gonçalves**作为一名开发人员和系统分析师开始了她的职业生涯。在最近的四年里，她决定研究IT的业务领域。她在敏捷管理的团队中从事IT业务分析工作，成为了一名敏捷爱好者，研究敏捷方法论、系统和业务分析技术，撰写和发表了多篇相关的文章和博客，偶尔在会议和研讨会上发表这些主题的演讲，并且渴求自己做得更好。 **查看英文原文**：[http://www.infoq.com/articles/roadmap-agile-documentation](http://www.infoq.com/articles/roadmap-agile-documentation)

> 原文出处：http://www.infoq.com/cn/news/2009/08/agile-documentation [敏捷宣言提出](http://agilemanifesto.org/ "敏捷宣言提出")：“可以工作的软件胜过面面俱到的文档”。这使得很多团队认为敏捷项目中不需要有文档。敏捷评论家们纷纷把有限的文档看作敏捷方法学的弱点。Ron Jeffries提出，敏捷并非推崇不需要文档或很少的文档，而是强调适当的文档化。他提到， > 大家对于XP的那个最普遍的质疑其实并不正确。他们认为我们觉得文档化是个坏主意。而XP其实致力于将对话的效率最大化。我们关于文档化的建议正是由此而来的。 如出一辙，Eelco Gravendeel也提出[敏捷中就只有两种文档](http://blog.xebia.com/2009/08/09/agile-documentation-the-good-the-bad-and-the-ugly/ "敏捷中就只有两种文档")， * **为了保证项目运行，所有团队成员都觉得有需要的文档** ——在理想情况下，团队在同一个地方一起工作，所有的知识可以通过直接交流得到共享和传播。然而，如果是分布式的团队，知识就不得不通过文档进行传播了，附带一些的影音媒介应该更有效。这时团队至少需要有一套共同的文档规范，来保证大家都说“[普通话](http://www.c2.com/cgi/wiki?UbiquitousLanguage "普通话")”，能有相同的理解。 Eelco建议：需要多留意许多用于产品立项的文档，因为项目一结束它们就没用了；也就是说， > 一旦你承认，这些文档仅仅是为了符合产品立项流程而写的，当项目结束或产品发布以后，它们就没用了，那么，理所当然地，对那些主张你把文档做全并保证100%正确的声音，你就可以开始说不了！这就是为何写文档是项旷日持久（而且昂贵！）的工作的原因。一旦你认识到这一点，其实只需要写 到刚刚够用，能传话、起到备忘作用就好了，你也会理解形式也不那么重要了：写在纸上、给白板上的图拍个照、茶杯垫后面的草稿、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/news/2009/08/agile-documentation)

> 原文出处：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)

> 原文出处：http://www.infoq.com/cn/articles/practices-lean-documentation 我在业余时间的一项调研让我洞察到对高效率和高质量最重要的三件事就是知识、知识还是知识。最好的知识获取途径就是通过对话，与了解这方面知识的人的对话。不幸的是，很多情况下这样的人并不在身边。 当文档是唯一的知识传承手段时，本文将尝试帮助读者编写有效而实用的文档。本文中所展示的实践都是基于我在一家大型跨国公司的项目中的工作经验。 这一切源于一个开发人员对我说他有一个改善项目文档的想法。我们就集合了一组对改善文档感兴趣的人并就一些规则达成了一致。 [TOC] ## 好文档的规则 好的文档应该： * 能够快速方便地创建和更新。过时的信息比没有信息更可怕。 * 能够方便地提供正确答案。如果不能很方便地找到答案，就不会有人愿意使用。 * 不要代替人的交互。单独的个体和通过流程和工具的交互，这样对吗？ 为了达成能够满足上述规则的目标，我们制定了六个实践： ### 实践一——识别阅读文档的用户以及他们使用文档的原因 尽管这听起来显而易见，但是很少有人真正这么做。在我们的项目中，我们的改进团队识别了四个目标群组。 * 需要我们的工作内容的简短总结的经理 * 需要快速介绍的新加入的开发人员 * 经过几年其它项目之后重返当前项目的原系统开发人员 * 帮助客户解决问题的故障排除人员  当我们问起他们对文档的需求是，第一个目标群组用户相当惊喜。首先，之前从未有人问过他们。哇！其次，他们甚至从未使用过他们所拥有的大量文档。这一目标群组只需要三件事情的答案。总的来说，他们所需要的就是三行文档。其他的文档对于读者和编者都是浪费时间。我的天！ ### 实践二——像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**](http://blog.crisp.se/author/tomasbjorkholm)在瑞典斯德哥尔摩的Crisp公司担任敏捷方法的教练和训练员。他对不断成长的团队，特别是大型企业中的团队，有着巨大的热情。他的使命是让敏捷方法更易于理解和采用。Tomas著有两本著作，瑞典语版本的《敏捷方法指南》和即将出版的《30天学会Kanban开发》。 **查看英文原文：**[Lean Documentation](http://www.infoq.com/articles/practices-lean-documentation)