敏捷文档你需要知道的.pdfVIP

目 录 如何撰写好文档 ？精益文档的六个实践 用户故事驱动的文档 两种类型的敏捷文档——不多不少 ，刚刚好 ！ 敏捷文档编制路线图 Readme.io创始人谈API文档的未来 本文档使用 看云 构建 - 2 - 如何撰写好文档 ？精益文档的六个实践 如何撰写好文档 ？精益文档的六个实践 原文出处 ：http///cn/articles/practices-lean-documentation 我在业余时间的一项调研让我洞察到对高效率和高质量最重要的三件事就是知识、知识还是知识。最好的 知识获取途径就是通过对话 ，与了解这方面知识的人的对话。不幸的是 ，很多情况下这样的人并不在身 边。 当文档是唯一的知识传承手段时 ，本文将尝试帮助读者编写有效而实用的文档。本文中所展示的实践都是 基于我在一家大型跨国公司的项目中的工作经验。 这一切源于一个开发人员对我说他有一个改善项目文档的想法。我们就集合了一组对改善文档感兴趣的人 并就一些规则达成了一致。 好文档的规则 实践一——识别阅读文档的用户以及他们使用文档的原因 实践二——像Google Earth那样组织文档 实践三——保持小规模 实践四——让文字读起来更吸引人 实践五——结合可视化元素 实践六——让文档易于维护 结果 关于作者 好文档的规则 好的文档应该 ： 能够快速方便地创建和更新。过时的信息比没有信息更可怕。 能够方便地提供正确答案。如果不能很方便地找到答案 ，就不会有人愿意使用。 不要代替人的交互。单独的个体和通过流程和工具的交互 ，这样对吗 ？ 为了达成能够满足上述规则的目标 ，我们制定了六个实践 ： 实践一——识别阅读文档的用户以及他们使用文档的原因 尽管这听起来显而易见 ，但是很少有人真正这么做。在我们的项目中 ，我们的改进团队识别了四个目标群 组。 需要我们的工作内容的简短总结的经理 本文档使用 看云 构建 - 3 - 如何撰写好文档 ？精益文档的六个实践 需要快速介绍的新加入的开发人员 经过几年其它项目之后重返当前项目的原系统开发人员 帮助客户解决问题的故障排除人员 当我们问起他们对文档的需求是 ，第一个目标群组用户相当惊喜。首先 ，之前从未有人问过他们。哇 ！其 次 ，他们甚至从未使用过他们所拥有的大量文档。这一目标群组只需要三件事情的答案。总的来说 ，他们 所需要的就是三行文档。其他的文档对于读者和编者都是浪费时间。我的天 ！ 实践二——像Google Earth那样组织文档 用户使用文档是为了找到他们的问题的答案。可以通过找到正确答案所需要的时间来衡量文档的质量。我 们用Google Earth作为模型。 你是否曾试图在Google Earth上找到你的房子 （通过下钻而不是搜索地址的方式 ）？它花费了你多长时 间 ？大概30到60秒 ？在地球表面找到你的房子就像在1.5万亿 （1.5*1012 ）个答案中找到其中一个答案一 样。即使系统十分复杂庞大 ，找到答案的时间也不应该超过60秒。 如何将这一模型应用到文档上呢 ？我们遵循了类似于Google Earth移动层级的层次结构 ：月亮级、卫星 级、航拍级和直升机级等。每一层级都有一个简短的介绍 ，我们称之为电梯间演讲 ，而且延续到下一层最 多只有九种可能。 本文档使用 看云 构建 - 4 - 如何撰写好文档 ？精益文档的六个实践 记住 ，并非所有的文档工具都适于下钻的方法。包含目录结构的Word文档可能就不是一个很好的主意。 有指向下层链接的wiki就好很多。 实践三——保持小规模 我们讨论了文档化的原因并得出如下最小化文档规模的原则 ： 文档应该是没有时间和位置限制的沟通方式。不应该是实时沟通的替代品。 我们应该只留存结果而非需求。也就是说只有在推出新功能时 ，我们才更新或替换文档而不是在拿到