手册形式的文档与清单形式的文档

Question

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

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

• 所讨论（子）系统的目的
• 为什么要这样配置
• 实施设置/程序时预期发生的事件
• 可能导致程序失败的潜在问题

然而，我对此投票反对，所以我的文档是必需的重写为“按顺序应用步骤 ABC 将解决问题 X”的形式。 我经常听到这样的抱怨：它需要放在一张纸上。 尝试通过一页文档以这种方式向某人解释 Squid ACL 的配置（包括故障排除）。这只是六份“等待编写”为恢复检查表的文档之一。

我所提倡的方法是否真的有些过了？或者他们是对的，我应该管好自己的事，给他们写一份简单的清单？我担心的是，无论你写得多好程序清单，它都无法真正解决需要系统管理员仔细思考的问题。如果你花时间做一份恢复程序清单，但最终却无法解决问题（因为还有其他因素不在文档中），由于该文件的重点狭窄)，并且该文档的目的是避免重新阅读手册页、wiki 和网站，那么我为什么要这样做呢？是我太担心了，还是这真的是一个问题？

编辑：

部门内目前没有帮助台职位。本文档的读者对象是其他管理员或部门主管。

Answer 1

当我写我自己的清单时，我总是分成两组三份。一份是完成清单，一份是更长的附录，介绍系统的架构，包括为什么这样做、上线时可能遇到的问题以及抽象的设计假设。接下来是可能出现的问题及其解决方案的列表，然后是更长的部分，其中包含有关系统如何工作、为什么这样做的信息，以及在发生特殊情况时为人们指明正确方向的其他有用信息。

在我上一份工作中，我们需要编写文档，以便即使是 1 级帮助台人员也能解决问题。这需要检查表，而这些检查表通常在编写后的 3 个月内就会过时。我们被强烈要求尽可能编写故障排除指南，但当应急树中有三个以上的分支时，如果不抽象，你就无法编写该文档。

什么时候离开在我上一份工作中，我在离职前交了一份 100 页的“如何做我的工作”手册。它包含抽象内容、设计理念以及集成点。由于我可能是为另一位即将接替我的系统管理员撰写的，所以我把它瞄准了那些能够将抽象概念转化为具体行动的人。

---

五年过去了，我发现我对此的看法已经有所改变。文档作为手册和以清单形式记录在文献的层次结构中占有非常重要的地位，两者都需要制作。但它们针对的受众却截然不同。

以清单形式记录

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

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

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

第二点是针对那些不经常运行但包含陷阱的程序。检查表就像一张地图，可以避免临时起意而导致的必然失败。如果将检查表保存在文档库中，那么就无需在旧管理员发送 HOWTO 时搜索电子邮件。

在我看来好的checklist-documentation 还包括关于可能出现故障点的部分，以及对这些故障的响应。这会使文档变得相当庞大，并引发同事的 TL;DR 响应，因此我发现将故障模式及其响应作为来自检查表的链接而不是页面本身的链接，可以使检查表变得不那么可怕。拥抱超文本性。

文档作为手册

这种文档的目标市场是那些想要详细了解系统工作原理的人。应该可以从这种文档中派生出“如何做某事”风格的文档，但更常见的是，我认为它是对清单式文档的补充，用于支持工作流程中做出的决策。

这是我们包含如下重要内容的文档：

• 解释为什么这样配置。
  • 本节可能包括一些非技术问题，例如有关如何购买和安装整个产品的政治问题。
• 解释常见的故障模式及其应对措施。
• 解释任何书面的和事实上的服务水平协议。
  • 事实上：“如果在期末考试周期间失败了，那就意味着一切都完了。如果是在暑假期间，那就回去睡觉，早上再处理。”
• 制定升级和重构目标。
  • 以后的政治可能会有所不同，为什么我们不纠正最初提出的一些坏主意呢？

这些对于全面了解整个系统都非常有用。您不需要全面了解就可以运行简单的人机自动化任务，您需要它来弄清楚为什么某些东西会这样损坏，并知道如何让它不再发生这种情况。

---

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

我明白，我同情你。

是的，DR 文档确实需要尽可能地像清单一样。
是的，由于事情可能以多种方式发生故障，DR 文档是最难用清单来记录的。

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

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

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

理想情况下，DR 文档包含几项不同事项的程序清单：

• 分类程序需要弄清楚什么出了问题，这将有助于识别……
• 针对特定故障情况的恢复程序。支持...
• 提前编写的恢复脚本有助于最大限度地减少恢复期间的人为错误。
• 关于故障案例、故障发生的原因以及含义的手册式文档。

有时，分类程序就是您为某些系统制作的所有 DR 文档。但有了它，凌晨 4 点的呼叫将更加清晰，执行恢复的高级工程师将能够更快地找到实际问题。

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

手动式故障案例文档是当没有恢复程序或恢复程序失败时使用的最后一道防线。它提供了所需的谷歌提示，也许可以找到遇到该问题的其他人以及他们如何修复它。

Answer 2

其实都不是，我们使用文档作为测试用例

话虽如此，我们已经写了相关文件手册形式的文档。我们制定了检查清单，但随着业务的发展，我们发现这些清单容易出错，并且确实会对整个系统造成影响。

然而我们确实有有点儿安装了“文档作为检查表”，也就是说 - 如上所述 - 我们广泛监控我们的服务。有一句话：

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

这完全是事实，但另一个应该是：

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

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

这些测试提供的检查表比任何手写的检查表都要好得多。它实际上是自我记录的，一旦我们遇到一些尚未监控到的故障，测试至少会添加到 Nagios 中，这样我们就可以免费获得两样东西：

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

“真正的”文档保存在 Wiki 中，其中提到了特定服务或测试的零碎信息。如果缺少了，人们会在我们需要进行迁移或需要处理时立即添加它，到目前为止，这种方法效果很好。

错误的文档也会很快被纠正，每次出现故障时人们都会开始查找文档并尝试使用其中的 HowTos 解决问题，如果有误，只需用您的发现进行更新即可。

试想一下，如果按照清单操作，却没有安装任何测试，而这些测试在应用后会显示绿色复选框，那么可能会产生哪些错误。我认为不可能将文档与监控分开。

Answer 3

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

对于帮助台（级别 1）类型，检查表是正确的选择；当然，这假定存在更高级别的支持和您描述的更深层次的知识。

如果文档是为系统组准备的，我总是宁可多写一些文档。如果有人（您自己）想用必要的背景信息编写更广泛的文档，那么拥有足够的文档就足够了——没有一个理智的人会阻止您！

Answer 4

我认为这显然取决于主题。并非所有事情都可以简化为简单的清单，也并非所有事情都需要详细的用户手册。

这听起来确实像是在谈论内部文档，根据我的经验，你不能只给出步骤列表，因为选择太多了。即使创建一个用户帐户也有一些选项（在我们的环境中），所以我们的“新帐户”文档按顺序列出了基本步骤，但每个步骤都有变化的描述。

另一方面，我们从来没有写过一份关于“如何在办公室里接线”的文档，但我们这份非常粗略的文档也不是一份清单——它提到了我们用于电缆颜色的惯例，强调你有更新列出连接的电子表格，就是这样。

所以，现在我已经写了这篇文章，我完全同意：逐步的清单对于许多流程来说根本不起作用。