如何撰寫技術文件

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

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

接著Audrey Watters介紹Django共同開發者Jacob Kaplan-MossWriting 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!很多時候,我們不見得能那麼幸運的擁有專業編輯的協助,但是換個角度設身處地審閱文件,運用工具找出基本的文法和用字的錯誤,至少是撰稿人必須做到的;三人行必有我師,同事、同儕也能提供許多寶貴的建議,我想這樣至少能做到起碼的品質保障吧。

Comments