在写我的书时，我总是专注于写两个三集。完成检查清单，以及有关系统体系结构的更长篇幅的附录，包括为何按原样完成事情，上线时可能遇到的问题以及抽象的设计假设。其次是可能的问题及其解决方案的列表，其后是较长的部分，其中包含有关系统工作方式，为什么这样做的信息，以及在某些独特情况发生时可以为人们指明正确方向的其他信息。
在我的上一份工作中，我们被要求编写文档，以便甚至1级帮助台人员都可以恢复工作。这需要清单，通常在撰写本文后的三个月内就已过时。我们强烈建议我们尽可能地编写故障排除指南，但是当偶然性树中包含三个以上的分支时，您就不能在不经过抽象的情况下编写该文档。
离开上一份工作时，我在离开之前上了100页的“如何完成工作”手册。它包含抽象的内容，设计理念以及集成点。由于我大概是为另一个要代替我的系统管理员而写的，所以我将其目标对准可以采用抽象概念并将其转变为具体操作的人员。
五年过去了，我发现我对此有一些看法。这两个文件的手册和文件的清单在文件的层次，并都需要制作非常有价值的地方。他们针对的受众非常不同。
文件作为清单
此类文档的目标市场是想要如何做某事的同事。它们有两种类型：
- 只是想知道如何做事而又没有时间仔细阅读十五页手册并为自己弄清楚步骤的同事。
- 这些过程分步相当复杂，但只需要偶尔运行一次即可。
不耐烦是第一类的驱动力。也许您的同事实际上并不想知道为什么必须将输出通过90个字符的perl regex进行管道传输，而只是为了关闭故障单而已。对于确实想知道原因的人，请在清单中明确包含这样的语句：“有关此工作流为何如此的详细说明，请单击此链接”。
第二点是针对不经常运行但包含陷阱的过程。该清单充当地图的角色，以避免“确定的末日”只附加翅膀。如果清单保存在文档存储库中，则省去了在老管理员发送HOWTO的时间内搜索电子邮件的麻烦。
在我看来，良好的清单清单文档还包括有关可能的故障点以及对这些故障的响应的部分。这可能会使文档变得很大，并在同事中触发TL; DR响应，因此我发现将故障模式及其响应链接到清单中而不是页面本身上成为链接，这使清单变得不那么糟糕。拥抱超文本性。
手册文件
这类文档的目标市场是想进一步了解系统工作原理的人们。操作方法样式文档应该可以从该文档中获取，但是更常见的是，我将其视为清单样式文档的补充，以备份工作流中做出的决策。
这是文档，其中包含诸如以下这样的耐嚼片段：
- 解释为什么以这种方式配置。
- 本部分可能包含非技术性问题，例如围绕如何购买和安装整个物品的政治。
- 解释常见的故障模式及其响应。
- 解释任何书面和事实上的服务水平协议。
- 实际上：“如果在决赛周失败，那就是一个万有的难题。如果在暑假期间，请回到睡眠状态，并在早晨处理它。”
- 制定升级和重构目标。
- 以后的政治可能会有所不同，为什么我们不解决开始时引入的一些坏主意呢？
这对于全面了解整个系统非常有用。您不需要全面的了解即可运行简单的人工自动化任务，而是需要它弄清楚为什么某些事情会破坏它的工作方式，并且知道如何使其不再执行该任务。
您还提到了灾难恢复文档，该文档必须是清单。
我了解，您对此表示同情。
是的，灾难恢复文档确实需要尽可能与清单类似。
是的，由于事情发生的方式有多种，因此灾难恢复文档最难以检查清单。
如果您的灾难恢复清单如下所示：
- 致电Dustin或Karen。
- 解释问题。
- 退后。
你有问题。那不是清单，而是承认该系统的恢复非常复杂，需要架构师来弄清楚。有时候，这就是您所能做的，但是请尽可能避免使用它。
理想情况下，灾难恢复文档中包含有关以下几件事的过程清单：
- 分诊程序，以找出什么地方出了错，这将有助于确定...
- 某些故障案例的恢复过程。由...支持
- 事先编写好的恢复脚本有助于最大程度地减少恢复过程中的人为错误。
- 有关失败案例，发生原因及其含义的手动样式文档。
分诊程序有时是您可以为某些系统制作的所有DR文档。但是有了它，意味着凌晨4点的呼出将更加清晰，并且进行恢复的高级工程师将能够更快地解决实际问题。
一些故障案例具有直接的恢复过程。记录下来。在记录它们时，您可能会发现以特定顺序输入命令列表的情况，这是脚本编写的一个很好的用例。它可以将96点恢复过程变成20点恢复过程。在逐个映射恢复过程之前，您永远都不会弄清楚是否可以编写脚本。
故障案例的手动样式文档是没有恢复过程或恢复过程失败时要使用的最后一个渠道支持。它提供了可能需要找到其他人的Google提示以及他们为解决该问题所做的工作。