为什么文档审计是必须的

如果您询问一群人关于优秀文档的品质，您可能会得到许多不同的答案，但准确性和易读性应该在每个人的清单上名列前茅。您的文档在发布之日很可能 100% 准确且非常易于阅读，但随着它们描述的产品不断发展，它们不可避免地会变得不那么准确和易读。

没错，即使是文档也会过时。如果您的内容正在发生这种情况，那么现在是进行文档审计的时候了。

什么是文档审计？

审计您的文档通常包括

• 阅读当前文本，并通过例如询问主题 matter 专家 (SME) 或测试已记录的行为来确保其仍然有效
• 删除因新功能而变得无用的旧程序和过时信息
• 简化随着您添加新注释和警告而变得过于复杂的解释和描述

花时间进行仔细的审查和重写使您能够找到并修复文档不再胜任工作的地方。根据我的经验，我估计审计一个章节需要一到两天的不间断写作时间（不包括随后的 SME 和同行评审）。所需时间量取决于章节的长度、需要多少额外的研究和测试、内容从技术角度来看的过时程度以及作者在这类重写方面的经验等因素。

一两天听起来很长——您甚至可能认为这比您能负担得起的时间还要多。或者，也许您想进行文档审计，但您的老板不认为它是“真正的工作”，因为它不会产生新的产出。好消息是有一些方法可以证明彻底的审查是值得的。

您如何衡量文档质量？

制作数字和图表绝对不是我最喜欢的事情，但当涉及到证明花费在审计上的时间改进了文档时，您就离不开它们。在本文的开头，我强调了优秀文档的两个重要特征：准确性和易读性。

确定您的文档是否准确似乎相当简单。如果关于产品的信息正确描述了产品的行为，那么该信息就是准确的。如果您可以成功地遵循说明，那么说明就是准确的。

另一方面，衡量易读性要棘手得多。幸运的是，有一些工具可以提供帮助：可读性评分、估计阅读时间和类似数据。如果您想尝试它们，请查看 diction 包提供的 style 命令或像 readable.io 这样的网站。

数据不会说谎

当我使用 readable.io 来比较审计前后几个章节的可读性数据时，我得到了惊人的结果。

两个版本之间的差异在产品概述章节中最明显，该章节描述了产品的目标、优势和组件。该章节仅提供一般概念解释，没有程序。

估计阅读时间的惊人下降（从 18 分钟到 8 分钟）是通过无情地削减冗余内容并消除大量重复文本来实现的。对于入门章节，仅描述基础知识并链接到其他章节或指南以获取更多详细信息即可。

在另一次审计中，这次是针对程序优先于概念描述的章节，阅读时间的减少不太显着。然而，消除句子中的冗余内容仍然有助于使其更易于阅读。

文档审计需要时间，但它们是值得的

我不得不多次证明审计的优点，例如当我正在编写三份大型指南时。我开始争论是否值得花时间重写已经存在的东西，尤其是在我们有这么多新产品功能要涵盖、这么多新内容需要编写的情况下。

我相信上面的前后比较证明它是值得的。经过审计的内容不仅对读者更友好；而且因为它通常更短，所以对于作者来说也更容易维护。

进行文档审计是一项投资：您花费大量时间阅读、重写、思考和再次重写。在规划阶段，这似乎是一种奢侈，但如果您正在处理过时的文档集，那么它绝对会得到回报——尤其是当您的目标是拥有高质量的文档时。