系統(tǒng)管理員應(yīng)該怎樣高效的書寫文檔
原創(chuàng)【51CTO精選譯文】本文是上周在美國召開的LISA大會(huì)的一個(gè)課程總結(jié)，課程內(nèi)容為“針對(duì)系統(tǒng)管理員的文檔技巧”，講師是Coffee Bean Software Pty Ltd軟件工程師Mike Ciavarella，他曾經(jīng)是Sun的Unix系統(tǒng)管理員，編寫過UNIX防火墻。Mike現(xiàn)在也是麥克米蘭的技術(shù)編輯和墨爾本大學(xué)的軟件工程課的講師。LISA會(huì)議全稱Large Installation System Administration，意為大規(guī)模服務(wù)器環(huán)境的系統(tǒng)管理，由USENIX和SAGE這兩個(gè)組織協(xié)辦。今年的第24屆LISA大會(huì)剛剛在上周落幕。本文作者Ben Cotton是來自Purdue 大學(xué)研究系統(tǒng)團(tuán)隊(duì)的系統(tǒng)研究工程師。以下為全文：
51CTO推薦專題：系統(tǒng)運(yùn)維秘訣
為什么系統(tǒng)管理員應(yīng)該學(xué)習(xí)編寫文檔
系統(tǒng)管理員在面對(duì)書寫文檔的要求時(shí)，總會(huì)拿“系統(tǒng)應(yīng)該自我記錄”或“我沒有時(shí)間寫文檔”為擋箭牌而拒絕編寫文檔，甚至還有人認(rèn)為“缺乏文檔使他的工作更安全”。Mike Ciavarella認(rèn)為這些觀點(diǎn)對(duì)系統(tǒng)管理員和組織都沒有任何好處，他在周二的“系統(tǒng)管理員需要知道的文檔化技巧”課堂上，不僅反駁了這些荒誕的理由，而且就如何更有效地書寫文檔從技術(shù)方面分享了他掌握的一些經(jīng)驗(yàn)。
我對(duì)這個(gè)課程特別感興趣，因?yàn)槲沂荈edora項(xiàng)目文檔小組的成員，事實(shí)上我已經(jīng)成為我們小組的文檔工作傳道士。我必須掌握更多的文檔編寫技巧，幫助整個(gè)團(tuán)隊(duì)寫出高質(zhì)量的文檔。我經(jīng)歷過因缺乏有用的文檔而造成不良后果的事故，我相信許多系統(tǒng)管理員應(yīng)該有類似的經(jīng)歷，因此改進(jìn)文檔工作對(duì)減少這類事故是至關(guān)重要的。不要把什么事情都裝在腦袋里，關(guān)鍵時(shí)候也許你人不在，也許你被糟糕的狀況嚇蒙而記不起了。正所謂好記心不如爛筆頭，如果你認(rèn)為寫文檔是一件枯燥的事情，那是因?yàn)槟氵€沒有愛上它。當(dāng)你認(rèn)真寫完一篇文檔后，你會(huì)發(fā)現(xiàn)自己的思路更有條理，也會(huì)學(xué)到許多新知識(shí)。因?yàn)閷懳臋n的過程就好像你站在講臺(tái)上給學(xué)生上課一樣，不能忽悠，你會(huì)發(fā)現(xiàn)原來自己是多么淺薄。因此寫文檔不僅是一件快樂的事，也是學(xué)習(xí)提高的捷徑，更不會(huì)因此而丟掉工作。
如何編寫文檔
編寫文檔時(shí)首先應(yīng)該考慮的是誰是目標(biāo)讀者。如果目標(biāo)讀者是管理員，客戶或管理層，那么文檔的風(fēng)格和內(nèi)容將有所不同。弄明白目標(biāo)讀者后，寫起文檔來思路也會(huì)更清晰，最終的文檔用途也更大。
高效編寫文檔的關(guān)鍵是在讀者已經(jīng)知道的需要知道的內(nèi)容之間建立起連接，列舉讀者已知的一些內(nèi)容可以幫助他們理解文檔和減少文檔被駁回的可能性。試問如果你寫的文檔目標(biāo)讀者都已經(jīng)全部了解了，那你這個(gè)文檔還有存在的必要嗎？同樣，如果你寫的文檔讓目標(biāo)讀者丈二和尚摸不著頭腦，那么他們會(huì)有興趣讀下去嗎？
重要的信息在文檔中可能會(huì)出現(xiàn)多次，但要注意措辭適當(dāng)，不要一味使用重復(fù)的字眼，那樣會(huì)讓讀者覺得你在反復(fù)炒剩飯。
編寫文檔時(shí)還需要注意語態(tài)。如果是技術(shù)文檔，常常使用被動(dòng)語態(tài)，如果是教學(xué)用文檔，使用主動(dòng)語態(tài)更好（編者注：這個(gè)比較適用于英文的情況）。此外還需要注意詞性，不要表錯(cuò)了情，會(huì)錯(cuò)了意。象對(duì)待卷宗一樣對(duì)待文檔是個(gè)好主意，舉證責(zé)任在撰稿者，前面沒有介紹過的東西在后面就不能提，否則在接受盤問時(shí)你會(huì)被問的四分五裂。
文檔寫完后，編輯和校對(duì)很重要。編輯最好由理解材料的人進(jìn)行，他們可以幫助重新排列文檔章節(jié)以提高可讀性；校對(duì)則需要敏銳的眼光審查拼寫和語法，校對(duì)人員不一定要完全了解文檔中的技術(shù)術(shù)語。經(jīng)過編輯和校對(duì)的文檔應(yīng)該拿給既不是目標(biāo)讀者，又不熟悉該主題的人閱讀。如果他讀完后不能根據(jù)文檔的內(nèi)容確定目標(biāo)讀者，那說明文檔還存在嚴(yán)重的問題。本來你是寫給同為系統(tǒng)管理員的人看的，但卻不見一條命令或操作步驟，這就好比是牛頭不對(duì)馬嘴，這樣的文檔只能被扔進(jìn)垃圾桶。
其他注意事項(xiàng)
系統(tǒng)管理員必須展示文檔對(duì)自己的工作和整個(gè)組織都是有益的，否則就沒有存在的必要。Mike建議文檔工作應(yīng)該作為一個(gè)定期評(píng)估的績(jī)效組件，促使系統(tǒng)管理員保持文檔更新。在文檔編寫工作中，不管是部門經(jīng)理，還是剛剛?cè)肼毜男率?，都可以參與到其中。例如，初級(jí)管理員可以幫助高級(jí)管理員寫一些局部?jī)?nèi)容，如一個(gè)安裝步驟，一條命令的參數(shù)解釋等。重要的是每個(gè)人都要參與。
有多人參與編寫相同的文檔時(shí)，就涉及到使用協(xié)作工具了。沒有哪一個(gè)協(xié)作工具是最好的，重要的是確定需求，選擇最適合的工具。一般來說，任何工具都能夠處理多種格式的文檔（如數(shù)字和印刷）。
文檔寫完后事情并沒有就此結(jié)束，還應(yīng)該定期評(píng)估和保持更新。確保文檔的準(zhǔn)確性非常重要，如果不這樣做，文檔就會(huì)漸漸失去其價(jià)值，這種情況在現(xiàn)實(shí)工作中是很常見的。一開始大家都興致勃勃地編寫文檔，當(dāng)寫完后就放在硬盤的某個(gè)角落，不管文檔記錄的事情如何變化，都無人再問津，久而久之，文檔就成了擺設(shè)，等到需要使用的時(shí)候才發(fā)現(xiàn)文檔已經(jīng)失效了。因此文檔應(yīng)經(jīng)常更新，養(yǎng)成良好的文檔維護(hù)習(xí)慣是成為優(yōu)秀系統(tǒng)管理員的必備素質(zhì)。
原文：http://blogs.usenix.org/2010/11/10/documentation-techniques-for-sysadmins/
【編輯推薦】
