基于用户故事的文档

编写文档的方法有很多，但文档编写者必须做出的一个基本区分是，最终文档的目标是：

• 描述产品、软件、解决方案等的“功能”以及如何使用这些功能，或者
• 解释为了执行任务以实现特定目标应采取哪些操作

这两种方法都有其有效用途，但在某些领域或用例中，其中一种方法比另一种方法更好。这也可能取决于谁在编写文档以及目标受众是谁。

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

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

另一方面，烹饪书中的食谱是面向操作的文档的经典示例，它通过解释明确的步骤来指导用户完成特定目标。好的食谱概述了各种先决条件（配料、工具、设备），并解释了如何以及按什么顺序使用它们以达到期望的结果。这种类型的文档应力求简洁明了。

考虑以下两个例子

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

用户故事

借鉴敏捷术语，面向操作的文档通常基于用户故事。用户故事是对实现目标的过程的定义。在敏捷开发中，用户故事用于证明为什么应该付出努力来实施新功能或修改现有功能，并从用户的角度描述功能的使用。

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

例如，一个用户故事可以像这样

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

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

基于用户故事的文档

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

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

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

理想情况下，两种类型的文档都应该得到充分体现，用户可以选择更适合他们情况的类型。项目的潜在贡献者会阅读全面的参考风格文档，以了解应用程序的各个方面。普通用户或管理员会阅读基于用户故事的文档，以了解如何执行特定程序以实现当前目标。

在现实中，文档编写者需要考虑其团队的能力，不仅包括编写文档，还包括维护文档。当资源稀缺时，最好从基于用户故事的文档开始，因为它可以相对快速地提供有用的信息，允许用户开始测试产品并提供反馈。

当文档团队面临维护或现代化现有的一组遗留的、基于功能的文档的任务时，基于用户故事的方法也是一个不错的选择。与其为了维护和改进可能不需要或用户难以导航的大量内容而捉襟见肘，不如逐步将现有文档转换为基于用户故事的部分，省略无法建立有效用户故事的部分。

吸引新的贡献者参与基于用户故事的文档也更容易，因为开始记录特定程序的学习曲线比期望潜在编写者开始记录应用程序的整个功能集要平缓得多。

总结

面向功能的文档和面向操作的文档（可以基于用户故事）对于不同的目的都很有用，编写者应在决定采用哪种方法之前权衡两种方法的优缺点。

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