我过去曾与我部门的其他人讨论过文档，特别是详细程度和要求。在他们看来，文档是当 X 件事情出错时要做的 Y 件事情的简单清单。
我不同意。我认为这假定 IT 中的所有问题都可以很容易地归结为简单的恢复程序清单。我认为它完全忽略了情况的复杂性，而且部门中的其他人并不总是对这个问题有深入的理解（这就是我写文件的原因——所以他们有一些东西可以参考) 文件应该包括一些基本的背景材料，例如：
- 相关（子）系统的用途
- 为什么以这种方式配置它
- 实施设置/程序时预期发生的事件
- 可能导致程序失败的潜在问题
但是，我对此持反对意见，因此需要将我的文档重写为“按顺序应用的步骤 ABC 将解决问题 X”的表格。 我经常听到有人哀叹它需要放在一张纸上。 尝试通过单页文档以这种方式向某人解释 Squid ACL 的配置，包括故障排除。这只是作为恢复清单“等待写入”的六份文件之一。
我提倡的方法真的太过分了吗？或者他们是对的，我应该在这里管我的事，给他们写一个简单的清单？我担心的是，无论您如何编写程序清单，它都无法解决需要系统管理员仔细考虑的问题。如果您花时间制定恢复程序清单，但最终无法解决问题（由于文档的关注范围狭窄，还有一些不属于文档的其他因素），以及文档是为了避免重新阅读手册页、wiki 和网站，那我为什么要通过这些议案？我只是担心太多，还是这是一个真正的问题？
编辑：
该部门目前没有服务台职位。文档的受众将是其他管理员或部门负责人。
实际上两者都不是，我们使用文档作为测试用例
话虽如此，我们已经编写了与Documentation As-a-Manual配套的文档。我们有清单，但在成长过程中，我们发现它们很容易出错，并且在整个系统上确实失败了。
然而，我们确实安装了一种“文档即清单”，也就是说 - 如上所述 - 我们广泛监控我们的服务。有句话：
这是完全正确的，但另一个应该是：
每当我们需要迁移服务时，我们只需保持“服务组”、“主机组”，无论适用什么（我们使用 Nagios，您可以从词汇表中猜到）打开，只要有一个红点就不会迁移在任何服务上。
这些测试提供的检查表比任何手写检查表都提供的要好得多。它实际上是自我记录，一旦我们有一些没有被监控的失败，测试至少会被添加到 Nagios，我们可以免费获得 2 样东西：
“真实”文档保存在 Wiki 中，提及特定服务或测试的可能性和结束。如果它丢失了，人们会在我们需要进行一些迁移或需要对其进行一些工作时添加它，到目前为止，这种方法效果很好。
错误的文档也会很快被消除，每次出现问题时，人们都会开始查找文档并尝试使用其中的 HowTo 解决问题，如果有问题，只需使用您的发现进行更新。
想想一个人可能会通过遵循清单而不安装任何测试可能会产生的错误，这些测试会在应用它们后给你一个绿色的复选框。我认为不可能将文档与监控分开。
在写我的时候，我一直致力于写
两套三套。get-er-done 清单，附有更长的关于系统架构的附录，包括为什么事情会以这种方式完成，上线时可能的症结，以及抽象的设计假设。接下来是可能出现的问题及其解决方案的列表，然后是较长的部分，其中包含有关系统如何工作、为什么这样做的信息以及其他有助于在发生独特事情时为人们指明正确方向的信息。在我的上一份工作中，我们被要求编写 doc，以便即使是 1 级帮助台人员也可以恢复原状。这需要检查清单，这些清单通常在撰写后 3 个月内就过时了。强烈敦促我们尽可能编写故障排除指南，但是当应急树中的分支超过三个时，您就无法在不抽象的情况下编写该文档。
离开上一份工作时，我在离开前上交了一本 100 页的“如何做我的工作”手册。它包含抽象的东西、设计理念以及集成点。因为我大概是在为另一个将要取代我的系统管理员写作，所以我的目标是那些能够将抽象概念转化为具体行动的人。
五年过去了，我发现我对此的看法发生了一些变化。Document as Manual和Document as Checklist在文档的层次结构中都有非常有价值的位置，并且都需要生成。不过，它们的目标受众非常不同。
文件作为清单
这种文档的目标市场是想知道如何做某事的同事。它们有两种类型：
急躁是第一种的驱动力。也许您的同事实际上并不想知道为什么输出必须通过 90 个字符的 perl 正则表达式进行管道传输，只是为了关闭工单。对于那些确实想知道原因的人，绝对要在清单中包含这样的声明，“要详细解释为什么这个工作流程看起来像这样，请点击这个链接”。
第二点是针对不经常运行但包含陷阱的程序。清单就像一张地图，可以避免只是随波逐流的末日。如果清单保存在文档存储库中，则无需在旧管理员发送 HOWTO 时搜索电子邮件。
在我看来，好的清单文档还包括有关可能的故障点以及对这些故障的响应的部分。这会使文档变得相当大并触发 TL;DR 同事的响应，因此我发现将故障模式及其响应设置为清单中的链接而不是页面本身会产生不可怕的清单。拥抱超文本。
文档为手册
此类文档的目标市场是想要更多地了解系统工作原理的人。how-to-do-a-thing 风格的文档应该能够从这个文档中派生出来，但更常见的是，我认为它是对清单式文档的补充，以支持工作流程中做出的决策。
这是我们包含此类耐嚼部分的文档，例如：
这对于全面了解整个系统非常有用。您不需要全面了解来运行简单的人工自动化任务，您需要它来弄清楚为什么某些事情会破坏它的做法，并知道在哪里让它不再这样做。
您还提到了必须作为清单的灾难恢复文档。
我明白，你有我的同情。
是的，DR 文档确实需要尽可能像清单一样。
是的，DR 文档对清单的抵抗力最强，因为有很多事情可以破坏。
如果您的 DR 清单如下所示：
你有问题。这不是一份清单，而是承认这个系统的恢复非常复杂，需要架构师才能弄清楚。有时这就是你所能做的，但如果可能的话，尽量避免它。
理想情况下，DR 文档包含一些不同内容的程序清单：
分类程序有时是您可以为某些系统制作的所有 DR 文档。但拥有它意味着凌晨 4 点的呼叫将更容易理解，进行恢复的高级工程师将能够更快地解决实际问题。
一些故障案例具有直接的恢复程序。记录它们。在记录它们时，您可能会发现以特定顺序输入命令列表的情况，这是编写脚本的一个很好的用例；它可以将 96 点恢复程序变成 20 点恢复程序。在逐个操作映射恢复过程操作之前，您永远不会知道是否可以编写脚本。
当没有恢复程序或恢复程序失败时，故障案例的手动式文档是最后使用的支持。它提供了可能需要的 google 提示，以便找到遇到该问题的其他人以及他们为解决该问题所做的工作。
这取决于您的文档的目标受众。
对于帮助台（1 级）类型，清单是正确的方法；当然，这假设您所描述的更深入的知识有更高级别的支持。
如果文档是针对系统组的，我总是倾向于选择更多文档。如果某人（您自己）想要编写具有必要背景信息的更广泛的文档，那么仅仅获得足够的文档就已经够难了——任何理智的人都不应该阻碍您！
就我个人而言，我尽量保持文档尽可能简单。它往往包括：
所以诚然，我的常见问题部分可能是对所发生的事情的简要描述以及如何解决它的点点演练。
我通常假设有问题的系统的读者有一些知识（除非它特别神秘）。我没有时间让我的大部分技术文档级别 1 或管理可读 - 但一个线索级别 3 应该没问题。
我认为这显然取决于主题。并非所有内容都可以简化为一个简单的清单，也并非所有内容都需要详细的用户手册。
听起来您确实在谈论内部文档，并且根据我的经验，您不能只列出步骤，因为选择太多。即使创建用户帐户也有一些选项（在我们的环境中），因此我们的“新建帐户”文档按顺序列出了基本步骤，但每个步骤都有对变化的描述。
另一方面，我们从来没有为“如何在办公室打补丁”写很多文档，但我们非常粗略的文档也不是清单——它提到了我们用于电缆颜色的约定，强调您必须更新列出连接的电子表格，仅此而已。
所以，既然我已经写了这个，我完全同意：一步一步的清单不会在很多过程中削减它。
我非常同意你的观点（赞成详尽的文档），部分原因是我已经习惯了对文档没有太大兴趣的前辈。正如在相关帖子中所说，将其写出来不仅对其他人有好处，而且可以帮助您更全面地了解您的环境并将其固化在自己的脑海中。这本身就是一个结束。
顺便说一句，我发现很多阻力来自一个奇怪的信念，即蹩脚/不存在的文档=工作安全。这种想法似乎是不诚实和阴暗的。
感谢您打破现状。
我记录了很多，我什至有一个文档优先级清单:-)，但是我不会记录可以被认为是通用知识的东西（即对问题的合理良好描述在谷歌的第一页中给出了答案）。
对于对这里感兴趣的任何人，我的 doc prio 清单（对我有用，可能不适合你，非常感谢评论和建议）：
清单很好，只要它不假装是完整的文档。我写的最后几篇文档分为两部分： XYZ for Users，其中包括有关如何使用它的漂亮屏幕截图；和 XYZ 用于系统管理员，其中包括它是如何设置的，以及为什么（甚至可能包括它存在的业务需求）、要避免的陷阱以及关于故障排除的部分。故障排除是我希望找到清单的地方。也许将清单编写为技术支持的 XYZ 可能有助于说明问题。
现在，仔细阅读字里行间，只关注清单，这表明我缺乏“大局”思维和长期计划，而我期望这些人： 只做过技术支持；或刚起步的初级管理员；或者忙于工作，没有时间去想它；或从未被迫考虑过；或者只是简单的不在乎。我不知道这些（如果有的话）适用于您的情况。
我对文档很感兴趣。我现在工作的公司觉得文档很重要，但是公司里有些人觉得自己没有时间写文档。除了最初这样做的人之外，这可能会使任何人的生活变得困难。
对于某些事情，我已经编写了分步说明。如果需要，您可以将其称为清单，但实际上并不是要进行物理检查。我将我的文档风格称为“幼儿园步骤”。它是根据我为 Windows 2000 考试之一准备的 MCSE 练习册设计的。步骤非常详细，但是粗体/斜体/字体的使用很容易掩盖，只需挑选出重要的部分，这样您就不需要在学习完这些步骤后阅读所有内容。
有些事情不适合逐步说明，因此我尝试提供尽可能多的配置数据。一些最终坚持下去的技术倾向的人会对他们面临的问题有更好的了解，并希望当出现问题时这会让他们的生活更轻松一些。