模块化文档并非新概念。以模块化方式编写文档，以便组合和重用，这种做法已经存在多年，并有许多拥护者和反对者。本文介绍了一种轻量级的文档模块化方法。其核心思想是通过用户故事更好地聚焦内容，从而改进内容。（请参阅基于用户故事的文档，了解基于用户故事的文档与基于功能的文档的比较。）
DITA 及其他
请允许我一开始就强调：这不是 DITA（文档信息类型化架构），该方法也并非受 DITA 启发。重点在于基于用户故事的文档，其模块化结构是一种实现目的的手段——简化创作、确保一致性并精简文档流程。
模块化如何帮助作者
为了尽可能简化编写基于用户故事的文档，我们提出了一些最佳实践。其中包括编写标准化模块并将它们组合在一起。以模块化方式构建文档并为几种基本内容类型使用模板，提供了以下几个优势：
- 鼓励一致性
- 支持内容块的重用
- 使新同事更容易参与文档贡献
通过将文档源存储在模块中，我们的目标是改进向用户呈现文档的方式。
模块和组件的模板
内容的主要单元和模块化结构的最基本元素是模块。通过组合模块，作者可以在称为组件的单元中构建用户故事。我们定义了以下三种模块类型：
- 步骤
- 概念
- 参考
已为每种模块类型和组件开发了直观的模板。这些模板提供了关于结构、风格和合适内容的指导。这些模板位于 GitHub 上的 模块化文档项目源存储库中。该存储库还有一个简洁的手册，解释了如何使用模板，包括以模块形式格式化的真实文档示例。
一致性和内容重用
从作者的角度来看，使用预定义的模板来创建模块化内容单元：
- 鼓励简洁性和一致性；以及
- 使作者更容易专注于内容本身，同时消除格式化和结构化的额外开销。
仍然需要作者的专业知识来确保技术准确性以及适当的语气和措辞。
当多位作者遵循模板结构时，他们之间的协作会更轻松。不仅在采用一致格式后，作者可以轻松地接手他人的工作，而且各个模块也可以在多个组件中轻松重用。
模块化如何帮助读者
模块化文档还有潜力显著提升用户体验。可以为用户提供动态、可定制的体验，提供许多访问和使用文档的新方式。
保留书籍并添加用户故事
指南、书籍和手册都为基于功能呈现文档提供了优势。这些格式非常适合全面的内容集，旨在提供有关特定产品的方方面面的详细信息。这种格式引导用户从头到尾阅读。
然而，模块化文档提出了其他呈现形式。除了从章节和段落中形成大型指南外，模块化结构还允许更动态地浏览、选择和使用内容。如果将模块用作用户故事组件的构建块，则可以独立显示各个用户故事。
根据需要自定义书籍
谨慎使用元数据允许用户将整个可用内容主体过滤到自定义的模块和组件集中。这使用户有机会仅选择与其特定兴趣领域相关的文档，甚至构建自己的指南。
更直接、更有针对性的方法
借助预定义的模板，将基于用户故事的文档构建为组件和模块，使文档工作更加直接，支持一致性，并允许高效的内容重用。
此外，模块化结构使文档能够以更好地满足用户需求的方式呈现给用户，创造更动态的体验，并通过利用元数据，可能提供基于用户特定需求的自定义文档子集。
在 Robert Kratky 的演讲 走向模块化：将传统文档转变为基于用户故事的内容 中了解更多关于模块化文档的信息，该演讲将在 欧洲开源峰会 上进行，峰会将于 10 月 23 日至 26 日在布拉格举行。
您有文章创意吗？请将您的故事提案提交至 open@opensource.com。
2 条评论