用户模块的接口文档_模块化文档：如何使作家和用户都满意

用户模块的接口文档

模块化文档并不是一个新概念。 在可以合并和重用的模块中编写文档已有很多年了，并且有很多支持者和批评者。 本文介绍了一种轻量级的文档模块化方法。 这个想法植根于通过通过用户故事更好地关注内容来改进内容。 （有关基于用户故事的文档与基于功能的文档比较的讨论，请参阅基于用户故事的文档。）

DITA和朋友

让我从一开始就强调：这不是DITA （ 文档信息键入体系结构），也不是DITA启发的方法。 重点是基于用户故事的文档，其模块化结构是达到最终目的的一种方法-简化创作，确保一致性并简化文档流程。

模块化如何帮助作家

为了使编写基于用户故事的文档尽可能简单，我们提出了许多最佳实践。 其中包括编写标准化模块并将它们组合在一起。 以模块化的方式构造文档并为一些基本内容类型使用模板具有以下优点：

• 鼓励一致性
• 实现内容块的重用
• 使为文档做出贡献的提议对新同事而言不再那么令人畏惧

通过将文档源存储在模块中，我们旨在改进向用户展示文档的方式。

模块和组件的模板

内容的主要单元和模块结构的最基本元素是模块 。 通过组合模块，作者可以在称为Assembly的组件中构造用户故事。 我们定义了以下三种类型的模块：

• 程序
• 概念
• 参考

已经为每种模块类型和装配体开发了直观的模板。 模板提供有关结构，样式和适当内容的指南。 这些模板位于GitHub上的Modular Documentation Project源代码存储库中。 该存储库还提供了一个简明手册，其中解释了如何使用模板，包括格式化为模块的真实文档的示例。

一致性和内容重用

从作者的角度来看，将预定义的模板用于内容的模块化单位：

• 鼓励简洁和一致，并且
• 使您更容易专注于内容本身，同时消除了格式化和结构化的开销。

仍需要作家的专业知识来确保技术准确性以及正确的语气和声音。

当几个作者遵循模板结构时，他们之间的协作就不会那么痛苦。 当采用一致的格式时，作者不仅可以轻松地从别人留下的地方接管工作，而且各个模块也可以很容易地在多个程序集中重用。

模块化如何帮助读者

模块化文档还具有显着现代化用户体验的潜力。 可以为用户提供动态的，可定制的体验，该体验提供了许多访问和使用文档的新方式。

保留书籍并添加用户故事

指南，书籍和手册都为基于功能介绍文档提供了优势。 这些格式非常适合于全面的内容集，这些内容旨在提供有关特定产品的所有已知信息的详细信息。 该格式邀请用户从头到尾阅读。

但是，模块化文档建议其他形式的演示。 除了从各节和各章中形成大型指南之外，模块化结构还提供了更多动态方式来浏览，选择和使用内容。 如果将这些模块用作用户故事程序集的构建块，则可以独立显示各个用户故事。

根据需要定制书籍

精心使用元数据可以使用户将可用内容的整个主体过滤到自定义的模块和程序集中。 这使用户有机会仅选择与他们感兴趣的特定领域有关的文档，甚至建立自己的指南。

更直接，更有针对性的方法

在预定义的模板的帮助下，将基于用户故事的文档结构化为程序集和模块，使文档工作更简单，支持一致性并实现有效的内容重用。

此外，模块化结构使以更好地针对他们的需求，创造更动态的体验的方式向用户提供文档成为可能，并且通过利用元数据，潜在地可以根据用户的特定需求提供文档的自定义子集。

在10月23日至26日在布拉格举行的欧盟开源峰会上 ，罗伯特·克拉特基（Robert Kratky）的演讲“ 走向模块化：将传统文档转变为基于用户故事的内容”中了解有关模块化文档的更多信息。

你有文章的主意吗？ 将您的故事建议提交到open@opensource.com 。

翻译自: https://opensource.com/article/17/9/modular-documentation

用户模块的接口文档