基于用户故事的文档

编写文档的方法有很多，但是文档编写者必须做出的基本区别之一是生成的文档的目标是否是：

• 描述产品，软件，解决方案等的“功能”，以及如何使用这些功能，或者
• 说明为执行任务以实现特定目标而应采取的措施

两种方法都有有效的用途，但是在某些领域或用例中，一种方法比另一种更好。 它还取决于谁在编写文档以及谁是目标读者。

基于功能的文档与面向操作的文档

类似Unix的系统上的典型手册页是基于功能的文档的一个很好的例子。 理想情况下，它包含程序的所有功能（选项，命令，参数）的详尽列表，解释了这些功能的优点，并提供了如何使用它们的示例。 在这种类型的文档中，质量的度量是全面性和彻底性。

另一方面，食谱中的食谱是面向行动的文档的经典示例，它通过解释明确的步骤来指导用户完成特定目标。 一份好的食谱概述了各种前提条件（成分，工具，设备），并说明了如何处理这些前提条件以及以何种顺序获得预期的结果。 这类文档应力求简洁和说明性。

考虑以下两个示例：

Using onions Peeling onions Cutting onions Frying onions Using eggs Breaking eggs Mixing eggs with milk Frying eggs

制作洋葱蛋卷 建立工作场所 准备配料 选择香料 结合成分 煎蛋卷混合物 服务煎蛋卷 其他洋葱食谱

两种类型的文档都有时间和地点。 第一列是引用样式的内容。 它列出并描述了产品的各种属性，并告诉用户如何使用它们。 当用户想要了解产品的各个方面或用于参考目的（例如调试）时，此功能最为有用。 第二列涉及一个特定的目标，它将用户从A点带到B点。为此，它仅说明了为实现定义的结果而需要理解的产品功能或概念。 当用户手头上有需要完成的任务时，这是最有用的。

用户故事

面向行动的文档是从敏捷术语中借来的，通常基于用户故事。 用户故事是对实现目标的过程的定义。 在敏捷开发中，使用用户故事来说明为什么应该花费任何精力来实施新功能或修改现有功能，并从用户的角度描述功能的使用。

最常见的是，使用以下模板来识别用户故事： 作为<用户类型>，我想要<什么？>，所以要<为什么？>。

例如，用户故事可以如下所示：

作为管理员 ，我希望能够连接到服务器 ，以便可以管理用户帐户 。

用户故事描述的详细程度可以有所不同，这意味着高级用户故事（通常称为史诗）可以由许多较低级别的用户故事组成。

基于用户故事的文档

面向操作的文档可以基于用户故事，这有助于文档编写者确保他们写出用户实际需要了解的内容。 用户故事只有根据实际用户需求才有效。 这是一个不容忽视的重要考虑因素，因为它可以帮助减少需要开发和维护的内容量。

为了得出有效的用户故事，应该从所有参与方收集输入。 在一个开源项目中，它可以包括开发人员，测试人员，用户和文档编写者。 在企业环境中，需要来自客户的反馈，以及来自开发人员，支持团队，产品管理和内容策略角色的输入。

哪个更好：基于功能的文档还是面向操作的文档？

理想情况下，两种类型的文档都可以很好地表示，并且用户可以选择更适合其情况的类型。 一个潜在的项目贡献者将阅读全面的参考样式文档，以了解应用程序的各个方面。 临时用户或管理员将阅读基于用户故事的文档，以了解如何执行特定过程以实现近期目标。

实际上，文档编写者不仅需要考虑团队的能力来编写文档，还需要考虑维护人员的能力。 当资源稀缺时，通常最好从基于用户故事的文档开始，因为它可以使有用的信息相对较快地获得，从而允许用户开始测试产品并提供反馈。

当文档团队面临维护或更新一组现有的基于功能的旧版文档的任务时，基于用户故事的方法也是不错的选择。 不必费力地尝试维护和改善可能不需要或用户难以导航的大量内容，而是逐步将现有文档转换为基于用户故事的片段，而将有效的部分排除在外用户故事无法建立。

吸引新的贡献者加入基于用户故事的文档也更加容易，因为开始记录特定过程的学习曲线比预期的潜在作者开始记录应用程序的整个功能集的难度要小。

总结一下

面向功能的文档和面向操作的文档（都可以基于用户故事）对于不同的目的很有用，并且在致力于其中一种方法之前，作者应该权衡这两种方法的优缺点。

在不受时间或其他资源限制的理想世界中，将编写基于功能和面向操作的文档的完整版本。 在现实世界中，最好专注于基于用户故事的面向操作的文档，以更好地满足用户需求并减轻文档团队的负担。

翻译自: https://opensource.com/article/17/6/documentation-based-user-stories