系統管理員應該怎樣高效的書寫文檔
原創【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/
【編輯推薦】
