cmd命令在文档中编辑文档_在文档中采用简约

cmd命令在文档中编辑文档

传统的文档记录方法是解释所有内容，包括用户界面的功能。 我作为实习生的第一个尝试编写好的文档的项目是一个很好的例子（我的意思是可怕的 ），说明了这种方法的混乱程度。 但这还不止于此–一旦您开始记录所有内容 ，就很容易忽略用户的需求， 用户想要做什么以及用户难以完成的任务。

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

不必要。 MyHowTo.Org简要解释了该问题：

“越多越好”一词不适用于该文档。 至少在一定阈值之后。 如果每个人的文档过多，人们将不会阅读。 如果人们不阅读它，那么首先浪费时间来编写和维护此文档。 第二，它没有达到目的。 您拥有的文档越多，维护它就越困难（并且依赖关系不是线性的！）。 与旧系统失去联系的过时文档可能比缺少文档更糟糕。

解决方案

您如何避免过多解释的陷阱？ 好问题。

极简主义可以有所帮助。 文档世界的领导者JoAnn Hackos 概述了如何在文档中应用极简主义 ：

• 原则1：选择一种面向行动的方法。
• 原则2：将工具锚定在任务域中。
• 原则3：支持错误识别和恢复。
• 原则4：支持阅读以做，研究和定位。

简而言之，消除无关的信息。

简而言之，消除无关的信息。 关注用户需求是入门的好方法。 如果您可以概述用户要采取的​​行动或用户在继续之前需要的特定概念，则可以将有关产品的所有已知信息缩减为一个主题。 从那里，您可以采用该主题来确保用户可以完成其任务，并确定他们可能需要解决或减轻的潜在障碍。

将极简主义付诸实践

在Red Hat，我们会定期以极简主义为指导来进行剪辑。 一个作者以草稿状态提交一个主题，其他作者和编辑则使用经过修改的Hackos方法模板收集：

• 关注读者的目标； 采取面向行动的方法。
• 消除绒毛，冗长的介绍和不必要的上下文。
• 注重可发现性：最佳位置。
• 使用清晰的标题。
• 包括故障排除，错误恢复和验证步骤。

4月，我请我的同行作家和编辑审阅我撰写的概述文档草稿，该文档涉及Red Hat如何在Red Hat Subscription Management中使用Candlepin和Pulp引擎。 这个文档对我来说在技术上是困难的，并且我一直在努力如何最好地概述信息。 具体来说，因为这对我来说是个新话题，所以我担心在确保自己个人理解的过程中会添加太多细节，这对用户没有帮助。 这是我收到的反馈：

^{红帽作者和编辑对概述文档草案的反馈}

众包极简主义通过告诉我需要消除的内容，过度解释信息的地方以及需要添加更多信息的地方，帮助我实现了这一目标。 尽管我对保持文档的清洁和结构化非常感兴趣，但与标准的文档编辑/审阅相比，我仍然需要更多的帮助来实现这一目标。

想了解更多？

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

翻译自: https://opensource.com/article/17/10/adopting-minimalism-your-docs

cmd命令在文档中编辑文档