过去我曾与我部门的其他人讨论过文档，特别是详细程度和要求。 他们认为，当X事情出错时，文档是一个简单的Y清单。
我不同意。 我认为这假定IT中的所有问题都可以简单地归结为简单的恢复程序清单。 我认为它完全忽略了情况的复杂性，而且部门中的其他人并不总是对这个问题有深入的了解（这就是为什么我要写这个文档 – 所以他们有一些可以参考的东西）该文件应包括一些基本的背景材料，如：
不过，我对此很不满意，所以我的文档需要重新写入一个表单，上面写着“按顺序应用ABC步骤将解决问题X”。 我经常听到它需要放在一页纸上的哀叹。 尝试用这种方式向别人解释Squid ACL的configuration，包括通过单页文档进行故障排除。 这只是“等待被写入”作为恢复核对清单的六份文件之一。
我所倡导的方法真的太过分了吗？ 或者他们是对的，我应该介意我的事情，只是写一个简单的清单？ 我担心的是，不pipe你写了一个程序清单的程度如何，它确实不能解决一个需要系统pipe理员思考的问题。 如果你花时间做一个恢复程序的清单，最终不能解决问题（因为文件的重点不是很重要，因为还有其他因素不是文件的一部分），而且目的是文件是为了避免重新阅读手册页，维基和网站，为什么我要通过议案？ 我只是担心太多，还是这是一个真正的问题？
编辑：
目前在该部门没有帮助台的职位。 文档的读者将是其他pipe理员或部门负责人。
写我的时候，我一直都在写两三套。 “匆匆完成”清单， 附有关于系统体系结构的更长的附录，包括为什么事情按照自己的方式完成，上线时可能出现的困难点以及抽象的devise假设。 然后列出一系列可能的问题及其解决方法，然后是更长的一节，介绍系统如何工作，为什么这样做，以及其他有助于指导人们朝正确方向发展的信息。
在我上一份工作中，我们被要求写文档，以便即使是一级帮助台的人也能把事情恢复起来。 这需要清单，通常在写作3个月内已经过时了。 我们强烈要求尽可能编写故障排除指南，但是当意外事件树中有三个以上的分支时，您不能在不抽象的情况下编写该文档。
当我离开上一份工作时，在离开之前 ，我翻了一百页“如何做我的工作”手册。 它里面有抽象的东西，devise理念和整合点。 因为我大概是在写一个替代我的另一个系统pipe理员，所以我把它指向了一个可以抽象概念并将其转化为具体行动的人。
五年过去了，我觉得我的看法有所转变。 文件手册和文件清单在文档层次结构中都有非常有价值的地方，都需要生成。 不过，他们的目标截然不同。
logging为清单
这种文档的目标市场是同事想要如何做一件事情。 他们有两种types：
不耐烦是第一类的驱动力。 也许你的同事实际上并不想知道为什么输出必须通过一个90字符perl正则expression式，只是为了closures票。 绝对包括一个像“为了详细解释为什么这个工作stream程看起来像这个，请按照这个链接”的清单，为那些想知道为什么的清单。
第二点是程序不经常运行，但包含陷阱。 核对表就像一张地图，可以避免一定的厄运。 如果清单被保存在一个文档库中，那么它可以节省search邮件的时间，以便老pipe理员发送HOWTO。
在我看来， 良好的清单文档还包括可能的失败点的部分，以及对这些失败的回应。 这可以使文档相当大，并在同事中触发TL和DR响应，所以我发现将失败模式及其响应从检查列表中而不是在页面本身的链接上做出一个不重要的清单。 拥抱超文本。
文件为手册
这类文档的目标市场是那些想了解系统如何工作的人。 应该可以从这个文档中得到如何做的样式文档，但是更常见的是我将它看作是清单样式文档的补充，以备份在工作stream程中做出的决定。
这是我们包括这样耐嚼的片断的文件：
这对于全面了解整个系统非常有用。 你不需要全面的理解来运行简单的人工自动化任务，你需要弄明白为什么有些事情会打破它的方式，并且有一个想法让它不能再做这个事情。
您还提到灾难恢复文档必须是一个清单。
我明白，你有我的同情心。
是的，DR文档确实需要尽可能像清单一样。
是的，灾难恢复文档是最难抵制的，因为有多less种方式可以破坏。
如果您的DR清单看起来像：
- 打给达斯汀或凯伦。
- 解释这个问题。
- 退后。
你有个问题。 这不是一个清单，这是承认这个系统的恢复是如此复杂，需要一个架构师来弄清楚。 有时候这就是你所能做的，但尽可能地避免它。
理想情况下，灾难恢复文档包含几个不同的事情的程序清单：
分类程序有时是您可以为某些系统制作的所有DR文档。 但是，这意味着上午4点的召唤将变得更加清晰，进行恢复的高级工程师将能够更快地解决实际问题。
有些失败案例有直接的恢复程序。 logging他们。 在logging它们时，可能会发现命令列表按特定顺序input的情况，这对于脚本来说是一个很好的用例; 它可以把一个96点恢复程序变成20点。 您将永远不知道是否可以编写脚本，直到您按照操作映射恢复过程操作。
故障案例的手动样式文档是在没有恢复过程或恢复过程失败时要使用的最后一个沟渠反向停止。 它提供了所需的谷歌提示，可能会find其他人谁有这个问题，他们做了什么来解决这个问题。
实际上，我们也没有使用“ 文档”作为testing用例
这就是说，我们已经编写了随文档手册一起提供的文档 。 我们有清单，但是在增长的时候，我们发现它们很容易出错，而且整个系统真的失败了。
然而，我们确实安装了 “文件清单”，就像上面提到的那样，我们广泛地监控我们的服务。 有一种说法：
如果你没有监控它，你不是在pipe理它
这是完全正确的，但另一个应该是：
如果你没有监控它，你不logging它
无论什么时候我们需要迁移服务，只要保持“服务组”，“主机组”，无论什么适用（我们使用Nagios，你可以从词汇中猜测）打开，只要有一个单一的红点在任何的服务。
这些testing提供了比任何手写检查清单所能提供的更好的清单。 这实际上是自我logging，只要我们有一些没有被监控的失败，testing至less会被添加到Nagios，我们可以免费获得两件事情：
“真实”的文档保存在Wiki中，提到特定服务或testing的可能性。 如果缺less的话，一旦我们需要做一些移植或者需要做一些工作，人们会尽快添加它，到目前为止这种方法已经非常成功。
另外，很快就会纠正错误的文档，每次出现错误的时候，人们都会开始查找文档，并尝试用HowTos来解决问题，如果错误的话只是用您的发现进行更新。
只要想一想按照一个清单可能会产生的错误，而没有安装任何testing，在应用它们之后会给你一个绿色的checkbox。 我不认为可以从Monitoring中分离文档。
这取决于您的文档的目标受众。
对于帮助台（1级）types，清单是正确的方法; 当然，这就假定你所描述的更深层次的知识有更高水平的支持。
如果文档是针对系统组的，那么我总是会在更多的文档中犯错。 如果有人（你自己）想要用更为详尽的背景信息来编写更多的文档，那么只要有足够的文档来处理就足够了 – 没有一个理智的人应该阻止你！
我个人尽量保持文档的简单。 它往往包括：
所以我承认我的常见问题部分可能是对发生了什么事情的简要描述，以及如何解决这个问题的点状漫游。
我通常会从系统读者那里得到一些知识（除非特别神秘）。 我没有时间使我的技术文档大部分1级或pipe理可读 – 但一个线索级别3应该罚款。
我认为这显然取决于这个话题。 并不是所有的东西都可以简化成简单的清单，并不是所有的东西都需要详细的用户手册。
这听起来像是在谈论内部文档，根据我的经验，您不能只列出一个步骤，因为select太多了。 即使创build用户帐户也有一些选项（在我们的环境中），所以我们的“新帐户”文档按顺序列出了基本步骤，但是每个步骤都有对变化的描述。
另一方面，我们从来没有写过很多关于“如何在办公室打补丁”的文档，但是我们非常粗略的文档也不是一个清单 – 它提到了我们用于电缆颜色的惯例，强调您必须更新列出连接的电子表格，这是关于它。
所以，现在我已经写了这个，我完全同意：一步一步的清单不会削减很多进程。
我非常同意你的看法（赞成详尽的文档），部分原因是因为我习惯了对文档没有多less兴趣的前任。 正如在相关文章中所说的，写出来不仅对他人有好处，而且可以帮助你更全面地了解你的环境，并在你自己的脑海中巩固它。 这本身就是目的。
顺便说一下，我发现很多推迟来自一个奇怪的信念，即蹩脚的/不可靠的文档=工作安全。 这种想法看起来不诚实和阴暗。
赞美你的现状。
我的文档相当多，我甚至有一个文件优先清单:-)，但是我不会logging可以被认为是通用知识的东西（即对问题的合理的良好描述在谷歌的第一页内给出了答案）。
对于任何人在这里感兴趣的是我的文档prio清单（为我工作，可能不适合你，意见和build议高度赞赏）：
一个清单是好的，只要它不假装是完整的文件。 我写的最后几个文件分为两部分：XYZ用户，其中包括如何使用它的截图; 和XYZ（系统pipe理员），其中包括如何设置，以及为什么（可能甚至包括业务需求），要避免的陷阱以及有关故障排除的部分。 故障排除是我期望find清单的地方。 也许把技术支持写为XYZ可能有助于说明问题。
现在，在各行之间阅读，只关注清单，表明我缺乏“全景”的思想和长期规划，这是我从一个曾经做过技术支持的人所期望的。 或刚开始的初级pipe理员; 或者工作如此</s> they，他们没有时间思考; 或从未被推动去思考; 或者只是简单的不在乎。 如果有的话，我不知道哪一个适用于你的情况。
我在文档上很大。 我现在工作的公司认为文件很重要，但公司里的一些人觉得他们没有时间写文件。 除了原来做的人之外，这可以让任何人都难过。
对于某些事情，我写了一步一步的指示。 如果你愿意的话，你可以把这个清单叫做清单，但是这并不是真的打算进行物理检查。 我把我的文档样式称为“幼儿园步骤”。 它是在Windows 2000考试中的一门MCSE练习册之后形成的。 这些步骤非常详细，但使用粗体/斜体/字体可以很容易地进行光泽处理，只需挑选重要的部分，以便在学习完这些步骤之后不需要阅读所有内容。
有些东西不适合分步指导，所以我尽量提供尽可能多的configuration数据。 一些技术上倾向的人最终会坚持下去，他们会对自己所面临的问题有一个更好的认识，并希望当出现问题时能够让自己的生活变得容易一些。