技术写作的度量指标：如何衡量文档质量

我一直在思考一个问题：技术文档写得好不好，到底谁说了算？很多团队花了大把时间打磨产品手册，结果用户还是抱怨“找不到”“看不懂”。这背后其实是一个度量问题——你无法改进你无法衡量的东西。对于产品手册建设，我一直主张用数据驱动的方式去评估文档质量，而不是凭感觉。今天这篇文章就聊聊几个关键指标，从可访问性到可读性，看看如何让产品手册真正帮到用户。

技术写作的目标看似简单——帮助读者更好地使用某个产品，从而让他们的生活更轻松。这个范围可以很广，从介绍新款数码相机的信息，到复杂诊断软件的用户手册。无论是哪种情况，要达成目标，技术写作都必须具备高质量。但如何衡量呢？无论技术文档的类型如何，都有一些可以追踪和改进的指标，来提升文档质量。让我们从第一个开始。

技术文档有很多类型，但大多数文档的目的可以归结为一句话：为最终用户提供帮助。这就是为什么高质量的文档也易于访问。用户通常阅读技术文档是为了学习或解决问题，他们不想花不必要的时间去寻找文档。如果找不到，他们可能会感到沮丧，转而投靠那些文档更容易访问的竞争对手。那么，你能做些什么呢？我们来看看 WhatsApp 的例子。WhatsApp 官网上的帮助中心链接一目了然，用户无需在子页面或外部链接中翻找。例如，从 WhatsApp 主页点击三次鼠标就能找到关于更新应用程序的用户指南。

可访问性的另一个要素是，WhatsApp 文档没有要求读者“跨栏”才能阅读。除了易于定位，技术文档还应易于打开和阅读，无需安装特殊程序或应用。你可以通过浏览器访问上述 WhatsApp 文档，即使是最基本的计算机用户也至少有一个浏览器。或者，你也可以将文档制作成 PDF 或 MS Word 格式，这两种格式都被广泛使用，用户也很熟悉。例如，戴尔用户可以通过 PDF 格式或在浏览器中阅读用户手册。总而言之，如果用户难以找到或访问你的文档，那么即使拥有最友好、最精心制作的技术文档也意义不大。你在文档质量上投入的所有努力都可能白费。

想要拥有最高质量的技术文档？那就用优质内容来填充它。你技术文档中的内容质量并非总能客观衡量。质量取决于许多因素：主题有多复杂？信息有多准确？是否使用了清晰的写作风格？格式是否到位？这几个问题只是冰山一角。不过，有一些方法可以确保持续产出高质量文档：设定基准。技术作家兼博主 Tom Johnson 建议使用像下面这样的清单。正如他所说，根据一系列特征来评估文档，比试图用抽象标准来评估更好。清单越全面，文档质量的一致性就越高。Johnson 的清单包含 75 个特征。除了用标准清单评估文档，另一种产出优质内容的好方法是遵循风格指南。网上有许多指南可用，例如 SUSE 文档风格指南。它向读者提供技术写作的最佳实践，无论是格式、术语使用，还是其他数十个主题。无论你使用该风格指南还是其他指南，关键是要坚持遵循其做法，以使文档质量保持一致。文档质量可能是一个难以追踪的指标。但通过采用清单和风格指南等简单策略，你几乎可以立即提升它。

你可能知道，用户阅读技术文档并不是为了消遣或文学享受。当他们拿起这样的文档时，心里只有一个目的：解决问题或学习东西。用户想要实现这个目标，如果你在创建文档时注重可用性，他们应该不会有问题。但什么使文档具有可用性？肯尼索州立大学的技术交流专家 Cassandra Race 总结道：当用户能够快速、轻松地遵循文档并实现目标时，该文档就具有高可用性。为此，技术写作者应牢记用户很可能是第一次与产品交互，正如 Kesi Parker 提醒我们的那样。这意味着写作者应创建清晰、逐步的文档，无论是数码相机手册还是软件界面指南。例如，Google 为 Native Client（一个在浏览器中运行编译 C 和 C++ 代码的沙箱）创建了技术概述。它之所以对读者非常有用，是因为写作者以耐心的态度处理问题。他们没有假设读者了解该产品，并且没有跳过任何步骤。例如，技术概述中的小标题包括：为什么使用 Native Client？Native Client 的好处；常见用例；Native Client 的工作原理；Web 应用程序的结构；从哪里开始。如你所见，如果用户想了解 Native Client，其技术概述涵盖了所有基础。总之，可用性就是为读者提供能够实现其目的的文档。正如之前提到的 Tom Johnson 所说：编写有用且易用的文档并非易事。然而，关注其解决问题的目的并提供信息，对于提高其可用性乃至整体质量至关重要。

这听起来显而易见，但写作者应牢记用户会阅读他们的文本，并且阅读时应该能够理解。维多利亚大学的技术写作教授 Suzan Last 指出，每篇文档的根本目的就是被阅读。这就是为什么可读性至关重要，无论技术文档的类型如何。为了提高文本的可读性，你可以使用可读性指标和分数，例如 Flesch Reading Ease 分数，该分数考虑单词和句子长度。如上所示，该分数范围在 1 到 100 之间。分数越高，文本越容易阅读和理解。同时，该分数还附有估计的阅读年级。例如，如果文本得分在 80 到 90 之间，意味着六年级学生就能理解。你可以使用各种工具（如 Readable）检查 Flesch Reading Ease 分数，也可以在 MS Word 中查看。除了单词和句子长度，术语的存在也会显著影响可读性。如果你在写作中大量使用技术术语，可能会让大部分不具备你知识水平的读者望而却步。另一方面，即使是专家读者也会欣赏简洁明了的语言。像 Readable 这样的工具可以帮你识别术语和复杂性。总而言之，关注可读性不仅仅是让文本变短，而是确保你的文档能被目标受众有效理解。通过结合使用指标和明智的写作实践，你可以制作出既有用又易读的技术文档。

---

多站点，多语言，多版本；营销，推广，客户支持，官网，活动宣传，没有统一路径支持。自从有了Baklib ，这一切都得以解决。