如何为文档编写有效的检查清单

在匆忙发布文档时，您有很多事情要做。 您很可能会错过一些东西。 这可能是一件小事，也可能是一件大事。 但为什么要冒险呢？

发布检查清单可以帮助您避免犯错。 它可以帮助提高您的发布流程效率。 无论是纸质还是屏幕上的精心制作的检查清单，都可以确保您的文档发布顺利进行，并且您不会错过任何内容。

一个简单却强大的列表

检查清单应成为任何技术作家的工具包的一部分。 阿图尔·加万德在他的书 检查清单宣言 中写道

…… 检查清单这样简单的东西可以提供实质性的帮助，这远非显而易见。 我们可能会承认错误和疏忽…… 但我们认为我们的工作太复杂了，无法简化为检查清单。

检查清单的主要好处，特别是对于技术作家而言，在于它可以帮助您尽可能避免错误和疏忽。

有效检查清单的要素

有效的检查清单听起来很容易创建，但事实并非如此。 有效的检查清单不是简单的任务列表。 这是一个非常集中的列表，列出了您需要做的事情。 在这种情况下，它是您需要做的将文档发布给用户的事情。 您的检查清单应仅包含您需要且可以一目了然地吸收的信息。

发布检查清单应包含哪些内容？ 这将取决于几个因素，包括您要发布的文档的数量和类型、您发布文档的格式以及您交付文档的方式。

例如，如果您的文档是在 wiki 上交付的，则您无需包含有关将文档检入版本控制或生成 PDF 的项目。 但是，您需要列表中的项目来检查链接和格式。

您应该尽可能保持检查清单简短。 有多短？ 一页。 或更少。 列表中的项目不应是完整的句子。 相反，请用句子片段来写——例如，查找遗漏的标点符号 或 修复损坏的链接。

为什么要保持检查清单简短？ 较短的检查清单更容易理解和阅读。 您可以一目了然地看到您需要做什么，而无需阅读两行或更多行。 加万德提供了一个来自航空领域的绝佳例子

试飞员的清单简单、简洁明了——简短到可以放在索引卡上，其中包含起飞、飞行和滑行的分步检查。 它包含飞行员知道如何做的内容。

在创建检查清单时，请记住它不是操作指南。 检查清单的作用是提醒您需要做什么。 您应该已经知道如何执行列表中的任务。 如果没有，您应该学习如何执行它们或在您的团队中分配任务。

发布检查清单示例

这是一个我过去使用过的文档发布检查清单的示例

• 纳入最终技术审查
• 进行最终编辑审查
• 检查拼写
• 检查版本号
• 将所有分支合并到主分支
• 构建 PDF 手册
• 构建在线帮助
• 抽查 PDF 手册的格式
• 抽查在线帮助的格式
• 检查链接
• 编写发布说明
• 编写发布公告
• 将文档发布到项目网站
• 发布发布说明
• 在项目博客上发布发布公告

这个检查清单，经过一些调整，在我参与的大约 90% 的文档项目中都为我提供了很好的服务。

即使您创建了检查清单，您也需要进行多次迭代才能将其精简到基本要素。 这意味着在多次文档发布中对其进行测试，并与您的团队合作，了解哪些有效，哪些无效，以了解列表中需要什么以及不需要什么。

每次迭代都调整检查清单。 有时可能只需要几次尝试即可提出您需要的检查清单。 或者您可能需要直接回到起点。

但最终，您将拥有一个有用的工具，可以减轻匆忙发布文档的一些压力。