【51CTO精选译文】本文是上周在美国召开的LISA大会的一个课程总结，课程内容为“针对系统管理员的文档技巧”，讲师是Coffee Bean Software Pty Ltd软件工程师Mike Ciavarella，他曾经是Sun的Unix系统管理员，编写过UNIX防火墙。Mike现在也是麦克米兰的技术编辑和墨尔本大学的软件工程课的讲师。LISA会议全称Large Installation System Administration，意为大规模服务器环境的系统管理，由USENIX和SAGE这两个组织协办。今年的第24届LISA大会刚刚在上周落幕。本文作者Ben Cotton是来自Purdue 大学研究系统团队的系统研究工程师。以下为全文：
51CTO推荐专题：系统运维秘诀
为什么系统管理员应该学习编写文档
系统管理员在面对书写文档的要求时，总会拿“系统应该自我记录”或“我没有时间写文档”为挡箭牌而拒绝编写文档，甚至还有人认为“缺乏文档使他的工作更安全”。Mike Ciavarella认为这些观点对系统管理员和组织都没有任何好处，他在周二的“系统管理员需要知道的文档化技巧”课堂上，不仅反驳了这些荒诞的理由，而且就如何更有效地书写文档从技术方面分享了他掌握的一些经验。
我对这个课程特别感兴趣，因为我是Fedora项目文档小组的成员，事实上我已经成为我们小组的文档工作传道士。我必须掌握更多的文档编写技巧，帮助整个团队写出高质量的文档。我经历过因缺乏有用的文档而造成不良后果的事故，我相信许多系统管理员应该有类似的经历，因此改进文档工作对减少这类事故是至关重要的。不要把什么事情都装在脑袋里，关键时候也许你人不在，也许你被糟糕的状况吓蒙而记不起了。正所谓好记心不如烂笔头，如果你认为写文档是一件枯燥的事情，那是因为你还没有爱上它。当你认真写完一篇文档后，你会发现自己的思路更有条理，也会学到许多新知识。因为写文档的过程就好像你站在讲台上给学生上课一样，不能忽悠，你会发现原来自己是多么浅薄。因此写文档不仅是一件快乐的事，也是学习提高的捷径，更不会因此而丢掉工作。
如何编写文档
编写文档时首先应该考虑的是谁是目标读者。如果目标读者是管理员，客户或管理层，那么文档的风格和内容将有所不同。弄明白目标读者后，写起文档来思路也会更清晰，最终的文档用途也更大。
高效编写文档的关键是在读者已经知道的需要知道的内容之间建立起连接，列举读者已知的一些内容可以帮助他们理解文档和减少文档被驳回的可能性。试问如果你写的文档目标读者都已经全部了解了，那你这个文档还有存在的必要吗？同样，如果你写的文档让目标读者丈二和尚摸不着头脑，那么他们会有兴趣读下去吗？
重要的信息在文档中可能会出现多次，但要注意措辞适当，不要一味使用重复的字眼，那样会让读者觉得你在反复炒剩饭。
编写文档时还需要注意语态。如果是技术文档，常常使用被动语态，如果是教学用文档，使用主动语态更好（编者注：这个比较适用于英文的情况）。此外还需要注意词性，不要表错了情，会错了意。象对待卷宗一样对待文档是个好主意，举证责任在撰稿者，前面没有介绍过的东西在后面就不能提，否则在接受盘问时你会被问的四分五裂。
文档写完后，编辑和校对很重要。编辑最好由理解材料的人进行，他们可以帮助重新排列文档章节以提高可读性；校对则需要敏锐的眼光审查拼写和语法，校对人员不一定要完全了解文档中的技术术语。经过编辑和校对的文档应该拿给既不是目标读者，又不熟悉该主题的人阅读。如果他读完后不能根据文档的内容确定目标读者，那说明文档还存在严重的问题。本来你是写给同为系统管理员的人看的，但却不见一条命令或操作步骤，这就好比是牛头不对马嘴，这样的文档只能被扔进垃圾桶。
其他注意事项
系统管理员必须展示文档对自己的工作和整个组织都是有益的，否则就没有存在的必要。Mike建议文档工作应该作为一个定期评估的绩效组件，促使系统管理员保持文档更新。在文档编写工作中，不管是部门经理，还是刚刚入职的新手，都可以参与到其中。例如，初级管理员可以帮助高级管理员写一些局部内容，如一个安装步骤，一条命令的参数解释等。重要的是每个人都要参与。
有多人参与编写相同的文档时，就涉及到使用协作工具了。没有哪一个协作工具是最好的，重要的是确定需求，选择最适合的工具。一般来说，任何工具都能够处理多种格式的文档（如数字和印刷）。
文档写完后事情并没有就此结束，还应该定期评估和保持更新。确保文档的准确性非常重要，如果不这样做，文档就会渐渐失去其价值，这种情况在现实工作中是很常见的。一开始大家都兴致勃勃地编写文档，当写完后就放在硬盘的某个角落，不管文档记录的事情如何变化，都无人再问津，久而久之，文档就成了摆设，等到需要使用的时候才发现文档已经失效了。因此文档应经常更新，养成良好的文档维护习惯是成为优秀系统管理员的必备素质。
原文：http://blogs.usenix.org/2010/11/10/documentation-techniques-for-sysadmins/
【编辑推荐】
