484.【Unix/Linux】文档标准

如果你必须手动记录文档，我们的经验表明，维护文档最简单，也是最有效的方式就是简洁、轻量的文档作为标准。不用为组织编写系统管理手册，你要做的是编写大量单页文档，每页涵盖单个主题。从总体开始，再细化为多个包含额外信息的部分。如果你必须详细介绍更多别的细节信息，那就再多写一页，专门介绍特别难或复杂的步骤。

这种方法有以下几个优点。

• 高层管理人员可能只对环境的总体设置感兴趣。回答上级的问题或者召开管理讨论，知道这些就足够了。不要提太多细节，否则会引得老板干预其中。

• 以上对客户也适用。

• 新员工或在组织内担任新职务的人员需要对基础架构有一个全面的了解才能提高工作效率。让这些人淹没在各种信息中没有什么帮助。

• 使用正确的文档要比浏览长篇大论更有效。

• 你可以利用索引页使文档易于查找。管理员花费在信息查找上面的时间越少越好。

• 如果只用更新一页内容，保持文档处于最新状态就更容易实现。

最后一点尤为重要。使文档保持最新是一项巨大的挑战，时间不够时，首先放弃的就是更新文档。我们发现有几个方法可以保持文档持续更新。

首先，设定期望，要求文档言简意赅、切题、行文朴实。开门见山，重要的是把信息记录下来。没什么比指望把文档写成设计理论的毕业论文而使文档更快失效的事情了。别对文档要求得太多，否则你可能什么都得不到。考虑形成一种简单的表单或模板，以供系统管理员使用。标准结构有助于避免无从下手的焦虑，并能够知道系统管理员记录相关的信息，而不是一堆毫无价值的东西。
其次，将文档集成到流程中。配置文件中的注释就是一种最好的文档。哪里需要，它们就出现在哪里，而且几乎不花什么维护时间。大多数标准配置文件允许注释，即使那些不是特别喜欢注释的文件也可以有一些额外的信息隐藏在其中。
本地构建的工具要去将文档作为其标准配置信息的一部分。例如，设置新计算机的工具可能需要有关计算机所有者、位置、支持状态和计费等信息，即使这些实际情况不直接影响机器的软件配置。
文档不应造成信息冗余。例如，如果你维护全站的系统配置主列表，那就别在其他地方手动更新这些信息。在多个地方进行更新不仅浪费时间，而且随着时间的推移，不一致的情况也必然会逐渐显现。如果其他场合和配置文件需要此信息时，编写一个脚本，从主配置处获取（或更新）。要是不能彻底消除冗余，至少要清楚哪个来源是权威的。编写工具来发现不一致的地方，可以通过 cron 定期检查。
诸如 wiki、博客和其他简单的只是管理系统等工具的出现使得跟踪IT文档变得更加容易。设置一个位置，可以在其中找到并更新所有文档。但别忘了保持组织结构。一个 wiki 页面，却把 200 个子页面全都放在了一个列表中，这样的页面不仅冗长，还难以使用。请务必添加搜索功能，这样才能充分利用你的系统。