文档入门

我们在工作场所没有做任何文档记录。我是新手，请寻求入门指南。

我有几个问题：

• 系统管理员应编写和维护哪些基本文件？为什么这些这么重要？

• 如何使文档与系统保持同步？您如何最大程度地减少信息重复？

• 推荐指南，最佳做法，反模式？

自2003年以来，我一直在内部Wiki中记录所有内容。

伺服器

• 硬件规格
• 保修信息
• 网络信息
• 当然还有已安装的软件和配置

工作流程

例如，如何添加或删除用户以及授予他/她访问所有相关服务的权限

重要连结

• 链接到您的所有Web界面
• 链接到监视URL（nagios，munin，apc监视...）
• 链接到Wiki（用于印刷版！）

紧急指示

如果Intranet服务器/ Internet / Web服务器/等宕机了怎么办

重要：

选择一个易于导出为PDF的Wiki引擎！
如果您正在休假，运行Wiki的服务器已关闭并且没人知道该怎么办，这是没有用的，因为您的文档处于脱机状态

看一下twiki，docuwiki或mediawiki。

顺便说一句：

有一个OpenOffice.org插件可以直接写入mediawiki-非常方便。

编辑：

写下一些信息也很高兴/home/adminuser/maintenance。如果几个管理员在服务器上工作，这将很快完成并且非常有帮助。例如：

2009-06-27 -thorsten-
          running aptitude update && aptitude full-upgrade
          everything seems ok
2009-06-25 -andreas-
          cups-pdf wasn't reachable. restarted cups
2009-06-23 -thorsten-
          deleted old log under /var/log/squid
etc.

当您意识到每个人都想要（和需要）文档时，您还需要认识到没有人有时间阅读和研究这些东西。

因此，不要编写需要学习的文档-而是以允许某人在需要时快速找到所需信息的方式来构造文档-这很可能是在系统停机且CTO处于关闭状态时呼吸他/她的脖子。

考虑到这一点，一些建议...

• 避免大块文字
• 项目符号列表是您的朋友
• 清晰的图表是金色的
• 重复是一个好主意（1）
• 易于更新和扩展

（1）不要创造一种真理的来源，而要强迫人们追寻它。这个想法越重要，您应该越重复。

基本文档：

• 服务器文档-规格/磁盘布局/安装的软件/注意事项
• 通用程序-所做的任何不“琐碎”的事情都应记录一个程序，特别是如果它以前没有做过。

保持文档同步几乎可以“解决错误”。随之而来的是需要认识到文档可能并且已经过时，并且在不考虑文档的情况下不应盲目地遵循它。那里的文档可以帮助管理员完成任务，而不是一步一步地替换掉批判性思维的规则。

最大限度地减少重复-使用诸如Wiki之类的东西可以将文档链接在一起可以帮助实现此目的，而不是重复信息，您只需链接到它即可。问题在于编写文档的人需要知道他们将要复制的信息已经存在。这通常是组织良好的问题。

我发现创建模板是很大的帮助。在我的情况下，这是一个Word模板，但请使用任何适合您的套件。创建一个框架文件，并根据需要包含目录字段和节。一旦使用了几次并进行了微调，就可以更快地创建新文档。格式的一致性对于文档创建和以后使用都将有很大的帮助。文档需要存储在逻辑位置和逻辑目录结构中。

我个人反对重复这个简单的事实，因为它会使保养变得不必要地困难和费时。在适当的地方创建对其他文档的引用，而不是重复文档或文档的一部分。如果发生什么更改，则您永远不必一次或多次在多个位置更改相关文档，否则，您将有一组冲突的文档，这对任何人都没有帮助。

在创建文档时，请记住它的用途。以后有人需要使用它。在没有先验知识的情况下可以进行这项工作吗？

不是您问题的直接答案，而是正确方向的指针：

我发现Limoncelli和Hogan撰写的《系统和网络管理实践》（又名《 Sysadmin圣经》）非常有价值，因为它涉及“最佳实践”问题，例如文档。如果您还不了解它，请确保在有机会的情况下进行调查。

对我来说，最重要的考虑因素是使其易于使用。如果很难进行协调，那么人们会避免这样做。由于以下原因，我选择Trac的Wiki作为我们文档的媒介：

• 位于中央。

  任何一份文档的一份以上有效副本都会造成混乱。如果您能够将所有人（包括撰稿人和听众）介绍给同一个地方，则可以简化此过程。

• 简单的编辑和格式化。

  在漂亮的Word模板上花费大量时间，并浪费了上一位作者的样式。如果您不对此感到厌烦，那么随时随地进行编辑就更容易了，贡献者也更愿意这样做。使用TracLinks尽可能多地分离项目。

• 审核历史记录。

  重要的是要知道谁做出了什么更改，何时以及为什么进行了更改。如果您可以将其绑定到变更请求票证和配置提交日志中，那就更好了。SVN提交挂钩对此非常有用。