开始使用文档

Question

我们没有在我的工作场所做任何文件。我对它完全陌生，并要求提供一些入门指导。

我有几个问题：

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

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

• 推荐指南、最佳实践、反模式？

Answer 1

自 2003 年以来，我将在我们的内部 wiki 中记录所有内容。

服务器

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

工作流程

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

重要链接

• 链接到您所有的网络界面
• 链接到监控 URL（nagios、munin、apc-monitoring...）
• 维基链接（印刷版！）

紧急说明

Intranet server/internet/web server/etc 宕机怎么办

重要的：

选择一个可以轻松导出为 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.

Answer 2

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

因此，不要编写需要研究的文档——相反，以允许某人在需要时快速找到他们需要的信息的方式构建文档——这很可能是在系统宕机而 CTO 工作的时候顺着他/她的脖子呼吸。

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

• 避免大块文本
• 项目符号列表是你的朋友
• 清晰的图表是金
• 重复是个好主意（1）
• 使更新和扩展变得容易

(1) 不要创造一个真相来源并强迫人们去追捕它。想法越重要，你就越应该重复它。

Answer 3

基本文档：

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

保持文档同步几乎是“看到错误时修复它”的事情。与此同时，需要认识到文档可能并且将会过时，并且不应该在没有考虑到这一点的情况下盲目遵循。文档用于协助管理员完成任务，而不是逐步取代批判性思维的规则集。

尽量减少重复 - 使用诸如 wiki 之类的东西可以将文档链接在一起可以帮助解决这个问题，而不是重复信息，您只需链接到它。问题是编写文档的人需要知道他们将要复制的信息已经存在。这通常是一个良好组织的问题。