在文档中采用极简主义

传统的文档编写方法是解释所有内容，甚至包括用户界面的功能。 我作为实习生尝试编写优秀文档的第一个项目就是一个很好的（我的意思是糟糕的）例子，说明这种方法有多么混乱。 但不仅仅是这样——一旦你开始记录所有内容，就很容易忽略用户需要什么、用户想要做什么以及用户在完成什么任务时遇到困难。

过度解释概念和说明是您很容易陷入的陷阱。 开发人员和工程师有时会向我们技术文档编写人员施压，以确保用户对所有内容都有解释。 从表面上看，拥有更多信息听起来更好，对吧？

不一定。 MyHowTo.Org 简洁地解释了这个问题

“多多益善”的说法不适用于文档。 至少在超过某个阈值之后是这样。 如果每个人都有太多的文档，人们就不会阅读它。 如果人们不阅读它，首先编写和维护这些文档是在浪费时间。 其次，它没有达到目的。 您的文档越多，维护起来就越困难（而且这种依赖关系不是线性的！）。 与缺少文档相比，与真实系统失去联系的过时文档可能更糟糕。

解决方案

如何避免陷入解释过多的陷阱？ 问得好。

极简主义可以提供帮助。 文档领域的领导者 JoAnn Hackos 概述了如何在文档中应用极简主义

• 原则 1：选择以行动为导向的方法。
• 原则 2：将工具锚定在任务域中。
• 原则 3：支持错误识别和恢复。
• 原则 4：支持阅读以进行操作、学习和定位。

简而言之，消除无关信息。 关注用户需求是入门的好方法。 如果您可以概述用户尝试采取的操作，或者用户在继续操作之前需要的特定概念，则可以将您对产品的所有了解简化为一个主题。 从那里，您可以处理该主题以确保用户可以完成其任务，并确定他们可能需要绕过或减轻的潜在障碍。

将极简主义付诸实践

在红帽，我们定期使用众包的方式进行编辑，并将极简主义作为指导。 作者提交处于草稿状态的主题，其他作者和编辑则使用 Hackos 方法的修改模板进行收集

• 关注读者的目标； 采取以行动为导向的方法。
• 消除冗余内容、冗长的介绍和不必要的背景信息。
• 关注可查找性：最佳位置。
• 使用清晰的标题。
• 包括故障排除、 错误恢复和验证步骤。

在四月份，我请我的同事作家和编辑审查了我正在撰写的关于红帽如何在红帽订阅管理中使用 Candlepin 和 Pulp 引擎的概述文档草稿。 这份文档对我来说技术难度很大，我一直在努力思考如何最好地概述这些信息。 具体来说，因为这对 *我* 来说是一个新主题，所以我担心为了确保我个人理解它，会在过程中添加太多细节，这对用户没有帮助。 这是我收到的反馈

图片来源：

^{来自红帽作家和编辑关于概述文档草稿的反馈}

众包极简主义通过告诉我需要消除什么、哪里过度解释了信息以及哪里需要添加更多信息，帮助我实现了这一目标。 即使我个人对保持文档的简洁和结构化很感兴趣，但我仍然需要比标准的文档编辑/审查所能提供的更多帮助才能实现这一目标。

想了解更多？

这是 Ingrid Towey 在今年于俄勒冈州波特兰举行的 Write the Docs 大会上关于在文档中使用极简主义的演讲，利用极简主义。