文档作为手册与文档作为检查表

Question

我过去曾与我部门的其他人讨论过文档，特别是详细程度和要求。在他们看来，文档是当 X 件事情出错时 Y 件事情要做的简单清单。

我不同意。我认为这假定 IT 中的所有问题都可以很容易地归结为简单的恢复程序清单。我认为它完全忽略了情况的复杂性，而且由于部门中的其他人并不总是对这个问题有深入的了解（这就是我写文档的原因——所以他们有一些东西可以参考) 文件应包括一些基本的背景材料，例如：

• 相关（子）系统的目的
• 为什么以这种方式配置
• 实施设置/程序时对发生事件的预期
• 可能导致程序失败的潜在问题

但是，我对此持反对意见，因此需要将我的文档重新编写为“按顺序应用的步骤 ABC 将解决问题 X”的表格。 我经常听到有人感叹它需要放在一页纸上。 尝试通过单页文档以这种方式向某人解释 Squid ACL 的配置，包括故障排除。这只是作为恢复清单“等待写入”的六份文件之一。

我提倡的方法真的过火了吗？或者他们是对的，我应该管好我的生意，给他们写一个简单的清单？我担心的是，无论您编写的程序检查表有多好，它确实无法解决需要系统管理员仔细考虑的问题。如果您正在花费时间执行最终无法解决问题的恢复程序清单（因为由于文档的重点狭窄，还有不属于文档的一部分的其他因素），以及文档是为了避免重新阅读手册页、维基和网站，那我为什么要走过场？是我太担心了，还是这是一个真正的问题？

编辑：

该部门目前没有服务台职位。文档的受众将是其他管理员或部门负责人。

Answer 1

实际上两者都不是，我们使用文档作为测试用例

话虽如此，我们已经编写了与Documentation As-a-Manual一起使用的文档。我们已经制定了检查清单，但随着增长，我们发现它们容易出错，并且在整个系统上确实失败了。

然而，我们确实安装了某种“文档作为清单”，即 - 如上所述 - 我们广泛监控我们的服务。有句话说：

如果你不监控它，你就没有管理它

这是完全正确的，但另一个应该是：

如果你不监控它，你就不会记录它

每当我们需要迁移服务时，我们只需要保持“服务组”、“主机组”，无论适用（我们使用 Nagios，你可以从词汇表中猜到）打开，只要有一个红点就不会迁移在任何服务上。

这些测试提供了比任何手写检查表所能提供的更好的检查表。它实际上是自我记录的，一旦我们有一些未受监控的失败，测试至少会被添加到 Nagios，我们免费获得 2 件事：

• 我们知道什么时候失败
• 清单上的另一点

“真实”文档保存在 Wiki 中，其中提到了特定服务或测试的可能性和结束。如果它丢失，人们会在我们需要进行一些迁移或需要对其进行一些工作时立即添加它，到目前为止，这种方法非常有效。

此外，错误的文档会很快被解决，每次出现问题时，人们都会开始查找文档并尝试使用其中的 HowTo 解决问题，如果有误，只需使用您的发现更新它。

想想可能通过遵循清单而没有安装任何测试可能会产生的错误，这些测试在应用它们后会给你一个绿色的复选框。我认为不可能将文档与监控分开。

Answer 2

当写我的我一直演化成写2个三套。get-er-done 检查表，有一个更长的关于系统架构的附录，包括为什么事情是这样完成的，上线时可能的症结所在，以及抽象的设计假设。其次是可能的问题及其解决方案的列表，然后是更长的部分，其中包含有关系统如何工作的信息，为什么会这样，以及其他有用的信息，如果发生独特的事情，可以将人们指向正确的方向。

在我的上一份工作中，我们被要求编写文档，这样即使是 1 级帮助台的人也可以将事情恢复原状。这需要核对清单，这些清单通常在撰写后的 3 个月内过时。我们强烈要求尽可能编写故障排除指南，但是当应急树中的分支超过三个时，您就无法在不抽象的情况下编写该文档。

离开上一份工作时，我在离开前交了一份 100 页的“如何做我的工作”手册。它有抽象的东西，设计理念，以及集成点。因为我大概是为另一个将要取代我的系统管理员写作，所以我的目标是能够将抽象概念转化为具体行动的人。

五年过去了，我发现我对此的看法有所改变。这两个文件的手册和文件的清单在文件的层次，并都需要制作非常有价值的地方。不过，它们针对的是截然不同的受众。

文件作为清单

这种文档的目标市场是想要知道如何做某事的同事。它们有两种类型：

• 只想知道如何做一件事而没有时间翻阅十五页手册并自己找出步骤的同事。
• 步骤相当复杂的程序，但只需要偶尔运行一次。

不耐烦是第一种的驱动因素。也许您的同事实际上并不想知道为什么输出必须通过 90 个字符的 perl 正则表达式进行管道传输，只是为了关闭票证必须这样做。对于那些确实想知道原因的人，一定要在清单中包含类似“有关为什么此工作流程看起来像这样的详细解释，请点击此链接”之类的声明。

第二点适用于不经常运行但包含陷阱的过程。清单就像一张地图，可以避免只是摆弄它的某些厄运。如果清单保存在文档存储库中，则无需在旧管理员发送 HOWTO 时搜索电子邮件。

在我看来，好的清单文档还包括有关可能的故障点以及对这些故障的响应的部分。这会使文档变得相当大并在同事中触发 TL;DR 响应，因此我发现将故障模式及其响应设为来自清单的链接，而不是页面本身，这会形成一个不可怕的清单。拥抱超文本性。

文档为手册

这类文档的目标市场是想要更多地了解系统如何工作的人。how-to-do-a-thing 风格的文档应该能够从这个文档中派生出来，但更常见的是我把它看作是对清单风格文档的补充，以支持工作流程中做出的决定。

这是我们包含这样耐嚼的部分的文档，例如：

• 解释为什么这样配置。
  • 本节可能包括诸如围绕如何购买和安装整个设备的政治等非技术问题。
• 解释常见的故障模式及其响应。
• 解释任何书面和事实上的服务级别协议。
  • 事实上：“如果这在决赛周失败了，那就是一切问题。如果在暑假期间，早上回去睡觉并处理它。”
• 制定升级和重构目标。
  • 以后可能政治不一样了，我们为什么不修正一开始提出的一些不好的想法呢？

这些对于全面了解整个系统都非常有用。您不需要全面的理解来运行简单的人工自动化任务，您需要它弄清楚为什么某些事情会破坏它的方式，并知道在哪里让它不再这样做。

您还提到了必须是清单的灾难恢复文档。

我明白，你有我的同情。

是的，DR 文档确实需要尽可能像检查表一样。
是的，DR 文档对检查列表的抵抗力最大，因为事情可能会以多种方式被破坏。

如果您的 DR 清单如下所示：

1. 打电话给达斯汀或凯伦。
2. 说明问题。
3. 退后。

你有个问题。这不是清单，而是承认该系统的恢复非常复杂，需要架构师才能弄清楚。有时这就是你所能做的，但如果可能的话，尽量避免它。

理想情况下，DR 文档包含一些不同内容的程序清单：

• 分诊程序，以找出什么地方出了错，这将有助于确定...
• 某些故障情况的恢复程序。哪个支持...
• 事先编写好恢复脚本，以帮助最大限度地减少恢复过程中的人为错误。
• 关于失败案例、它们发生的原因及其含义的手册式文档。

有时，分类程序就是您可以为某些系统制作的所有 DR 文档。但是拥有它意味着凌晨 4 点的呼叫将更加清晰，并且进行恢复的高级工程师将能够更快地解决实际问题。

一些失败案例具有直接的恢复过程。记录它们。在记录它们时，您可能会发现以特定顺序输入命令列表的情况，这是脚本编写的一个很好的用例；它可以将一个 96 点的恢复过程变成一个 20 点的恢复过程。在逐个操作映射恢复过程之前，您永远不会知道是否可以编写脚本。

当没有恢复程序或恢复程序失败时，故障案例的手动式文档是最后一个要使用的沟渠逆止器。它提供了可能找到其他遇到该问题的人以及他们为解决该问题所做的工作所需的 google-hints。

Answer 3

这取决于您的文档的目标受众。

对于帮助台（级别 1）类型，检查清单是正确的方法；当然，这假设您描述的知识越深，支持水平越高。

如果文档是针对系统组的，我总是倾向于更多文档。如果有人（你自己）想用必要的背景信息编写更广泛的文档，那么拥有足够的文档就够难了——没有理智的人应该阻止你！

Answer 4

就我个人而言，我尝试使文档尽可能简单。它往往包括：

• [X] 应该做什么（要求）。
• [X] 如何在高层次上构建（设计）。
• 为什么我以我所做的方式实现了 [X]（实现方面的考虑）。
• [X] 的实现如何是非标准的（变通方法）。
• [X] 的常见问题以及如何解决它们（问题）。

所以不可否认，我的常见问题部分可能是对发生的事情的简要描述，以及如何解决它的点演练。

我通常假设所讨论系统的读者有一些知识（除非它特别神秘）。我没有时间使我的大部分技术文档达到 1 级或管理可读性 - 但是 3 级应该没问题。