寫文件是一種藝術

工作這幾年,總覺得大家似乎不太重視寫文件這件事。學校沒教就算了,進入職場後,想學去上寫文件的課,很抱歉,目前所有市面上的教育訓練中心都沒開這門課。如果想買書自修,類似的中文書沒有,英文書則都是在講English writing skill。對於想加強自己documentaion的人,真的沒有什麼進修的管道。寫文件也並非我的強項,只是工作這些年下來,自己寫了不少技術文件,也看了不少別人寫的技術文件,所以在此做一下心得分享。(這裡指的文件是交付給客戶的技術文件)

寫技術文件不是在寫小說
客戶"總是"很忙的,即使在不忙的時候,通常他們也會把看文件這件事的priority排在後面,所以請假設客戶會花很短的時間看文件。因此技術文件的內容盡量簡潔,不要有太多廢話,如果有需要大篇幅的說明,盡量以圖表或流程圖輔助,讓客戶可以在短時間就能一目暸然。

請把客戶當白癡
身為作者的你,理論上應該是最懂文件內容的人,不要預設立場以為客戶都會懂你寫的東西,就將部份內容簡短帶過或漏掉不寫。建議最好在文件完成後,多找幾個人幫忙看一下內容,有文件審查制度當然更好 (CMMI的文件審查是出了名的嚴謹,目的就是希望要交付給客戶的文件,其品質有一定的水準)。

用字明確,不要有太多模糊的空間
特別是這份文件是要拿給客戶確認的文件,例如需求規格書、系統操作手冊等。當廠商與客戶有爭議產生時,如果當時客戶已經確認需求規格書的內容,通常會去翻需求規格書作為證明。假如技術文件的用字保留給人太多糢糊的空間,則雙方各自表述,到時候的爭議就更大了,例如『所以他們決定X功能應該可以不要做』,是誰決定的?那是要做,還是不要做?應該寫的明確一點,如果這個內容很重要,會影響整個專案的決策,最好盡可能連前因後果及人事時地物都加上,讓客戶自己看了也百口莫辯,所以可以改成這樣,『因為X功能與現有的Y功能在業務上相衝突,所以客戶A在9/11的會議上說X功能不要做(見9/11的會議紀錄)』。

善用word做排版
大家都會使用word,但是word有很多排版的功能相信還是很多人不知道,例如如何加頁首頁尾、如何做目錄等。排版並不是(也不能)讓文件變花俏,而是給客戶專業的印象,這樣的印象會給文件加分不少,特別是那些看不懂技術文件的長官們(註),但在一些公家機關中,這些長官們卻偏偏是文件簽核的最後一關。建議大家可以去看WORD的排版藝術這本書,此書是我認為目前市面上寫的最好的Word書籍。

文件要隨時更新
即使文件已經完成了,仍要不時更新,確保它的內容是在最新的狀態。如果文件沒有一直更新,只停留在第一版,那就沒有任何參考的價值,也白費了作者在第一版時所花費的心力。建議可以用版本控管系統(version control system)輔助管理文件,市面上常見的版本控管系統有微軟的Visual SourceSaft、opensource的cvs和subverson等。

我認為寫文件是一種溝通,更是一種藝術。大型專案常有techical writer這樣的角色專門負責寫文件,一般規模的專案因為預算有限,所以常是SA(system analyst)要寫需求規格書、SD(system designer)要寫技術規格書,其他文件則多由專案經理一人包辦。文件是專案中很重要的一環,文件寫的好,將來在維護系統時會比較輕鬆,人員離職時的工作交接也會比較順利。

註: 長官指的是(業務單位)客戶的直屬上司,這些人都很好辨認,座位總是坐在大家的後面。

相關文章

如何將電腦畫面經由 Chromecast 投放到電視螢幕上

Mac與Android裝置傳輸檔案的方法

Chrome 的檔案續傳功能

使用 Line Bot API 製作聊天機器人