☰

开始使用文档

tag-icon • tag-icon documentation
开始使用文档

我所在的公司还没有做过任何文档记录。我对此完全陌生，希望得到一些入门指导。

我有几个问题：

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

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

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

答案1

自 2003 年以来，我一直在记录一切在我们的内部维基中。

服务器

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

工作流程

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

重要链接

  • 链接到所有 Web 界面
  • 链接到监控 URL (nagios、munin、apc-monitoring……)
  • 链接至 wiki（获取印刷版本！）

紧急指示

如果内部网服务器/互联网/网络服务器等出现故障该怎么办

重要的：

选择易于导出为 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.

答案2

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

因此，不要编写需要研究的文档 - 相反，以一种允许人们在需要时快速找到所需信息的方式构建您的文档 - 这很可能发生在系统崩溃并且 CTO 正在催促他/她的时候。

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

  • 避免大段文字
  • 项目符号列表是你的朋友
  • 清晰的图表至关重要
  • 重复是个好主意（1）
  • 轻松更新和扩展

（1）不要创造一真理的来源，并迫使人们去追寻它。这个想法越重要，你就越应该重复它。

答案3

基本文档：

  • 服务器文档 - 规格/磁盘布局/已安装的软件/任何值得注意的内容
  • 常见程序——任何非“琐碎”的事情都应该有一个记录下来的程序，尤其是那些以前没有做过的事情。

保持文档同步几乎就是“发现错误就修复”的事情。与此同时，还需要认识到文档可能会过时，并且会过时，不应盲目遵循而不考虑这一点。文档是为了协助管理员完成任务，而不是成为一套取代批判性思维的循序渐进的规则。

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

答案4

虽然这不是您问题的直接答案，但却指向了正确的方向：

我发现系统与网络管理实践由 Limoncelli 和 Hogan 编写的《系统管理员圣经》非常有价值，因为它涉及“最佳实践”问题，例如文档。如果您还不了解它，请务必在有机会时研究它。

相关内容