如何撰寫技術文件

改善技術文件的品質，是新工作的任務之一，我打算在上任前先做點功課，喝過今天的第一杯咖啡，上網找了些相關資料，正巧 ReadWriteWeb 的作者Audrey Watters上週發表了一篇短文： Tips for Writing Good Documentation，簡明扼要的介紹了撰寫技術文件的觀念，但沒有涉入太多細節，看來是不錯的起點。

確認文件的讀者是誰，是 Audrey Watters 談到的第一個基本觀念，不論是平面的文字還是立體的簡報，目的都是「傳達」某些訊息給受眾（ audience），所以了解文件的目的，弄清楚讀者的知識背景、偏好的 接收訊息方式，都是製作文件前最基本、必要的前置作業。可是，真正落實這個「大家都知道」的觀念，踏實做準備功課的撰稿人，並不太多！

接著Audrey Watters介紹Django共同開發者Jacob Kaplan-Moss的Writing Good Documentation系列文章，Jacob 把技術文件分為三大類：Tutorial、Topial Guide 和 Reference Guide，每種文件類型有各自不同的目的和重點，然後 Jacob 在 Technical Style中介紹了他認為值得推薦的學習路徑，以及參考書籍（作者考慮的是用英文撰寫文件的情形，如果是用不同的語言撰寫文件，參考書籍必然要因地制宜做修改），最後他談到什麼是比較理想的文件風格（Style）。

Jacob 關於風格的建議可從兩個角度來分析，一個是老貓常提到的易讀性的考量，比如說字型、行距、空間配置等等，另外一個角度則是敘事說理的文字表達方式的考量。前者考慮的是讓讀者看的「舒服」，讀者閱讀技術文件的目的不外乎吸收知識或是解決問題，什麼樣的版型、字型配置，能讓讀者迅速找到他需要的資訊，是技術文件極重要的課題。後者是文字內容本身的可讀性和合理性，文件的目的是要傳達訊息給讀者，能讓人「看的懂」是重中之重的要務。

要讓人看的「懂」的要求可不是廢話，文筆通順沒有錯字只是文件最起碼的要求，如何才能讓讀者在最快的時間內讀懂一個觀念，或是學會如何操作一個軟體和機器，個中學問實在是不簡單。比如說是否以例子來帶動敘述，或是要不要用對話體例來說明新觀念、新事物；有些表達方式，和文字的特性有關，比如英文的時態（tense），主動和被動態（active/passive voice）等等。筆者的第一篇學術論文，在整理相關文獻（related works; literature reivew）時，引用了領域內開山祖師成名作裡面定義專有名詞的句子，被指導老師批評 ambiguous；有些人為了體現論文的權威性和客觀性，認為論文裡的敘述句都要用被動態，「我們觀察到一個現象」都要改成 It is observed that...。

還有，中文在處理主詞和第三人稱時，比英文要簡潔許多，而英文常見到的 ... of ... of ... of 的句子，若是要用中文表達，就得拆成幾個短句才行。語言的特性必然影響文件的撰寫方式，不同性質的文件，對於某些特性的「敏感度」又有所不同，「通順易曉」的要求說來簡單，執行起來難度不小。像白居易那樣，詩能寫的老嫗能解，實在是了不起啊！

最後，Jacob 提了You need an editor 的建議 - If you really want to produce great documentation, it needs to be edited！很多時候，我們不見得能那麼幸運的擁有專業編輯的協助，但是換個角度設身處地審閱文件，運用工具找出基本的文法和用字的錯誤，至少是撰稿人必須做到的；三人行必有我師，同事、同儕也能提供許多寶貴的建議，我想這樣至少能做到起碼的品質保障吧。