工程師該如何寫好文件?

軟體工程師除了要寫好程式，也需要會寫作。先前 Meta 的主任工程師 Ryan Peterman 曾經發過一條推文，內容寫說最重要的語言不是 Python、C++、Rust 或 Java，而是英文，因為軟體開發是需要大量合作的，而寫作在這個過程中，是高頻率會被用到。

具體來說，技術設計文件、技術會議討論、程式碼審查 (code review) 等等場合，都是需要寫作。當然 Ryan Peterman 提的英文可以替代成其他的自然語言 (例如我們使用的繁體中文)，不過核心概念不變，寫作能力提升，對軟體工程師的職涯幫助會很大。

為什麼要寫文件? 有什麼好處?

在談如何寫好文件前，想先談一下為什麼要寫文件? 寫文件有什麼好處? 很多人會覺得寫文件是種麻煩，所以會傾向不寫；但如果能理解寫文件帶來的好處，提升自己去寫文件的意願，長期來看對職涯會有幫助。

先從個人的角度來看，對個人而言寫好文件的槓桿很高，因為：

• 寫文件時，能幫助自己想得更清楚：很多關於技術設計的想法，比起在腦中想，寫下來的過程，能幫助自己思辨地更透徹。
• 讓影響力能擴大：很多事情能透過文件化來節省時間，舉例來說，假如要教導團隊中的新成員，沒有文件下，可能每次有人入職就要重複教一次。當有文件後，可以讓新成員直接看文件，這時就能用 O(1) 的成本來協助未來所有新成員理解某個概念。
• 在升遷時能被看見：Walmart 的資深工程總監 Louie Bacaj 先前分享過，寫好文件對升遷的幫助，並不亞於寫好程式碼。當你寫的文件被許多人閱讀，並能有效幫助團隊成員學習某個概念，這會對升遷非常加分。

對團隊與公司來說，寫文件的好處也很多

• 確保關鍵知識不會遺失：很多時候，隨著有人離職、團隊改組，很多關鍵知識會遺失，這要去找回來可能成本很高，如果有文件化，就能免去這些成本。
• 資深成員的時間可以被釋放：從團隊生產力的角度來說，如果某個問題被問第一遍時還沒有文件，這時如過已經可以預期接下來會有其他人也問同樣問題，那就是該寫文件的好時機。因為當這時有文件，資深工程師就可以省下解釋的時間，去做其他更重要的事。
• 新團隊成員可以獨立運作：許多新團隊成員，可能會擔心太過頻繁找人問問題，會打擾到別人，雖然如果在一個健康的團隊中不該有這種擔心，但更理想的狀況是，團隊文件化夠好，讓新團隊成員可以直接獨立運作。

程式碼寫好，不代表不用寫文件

讀完上面的這些列點，有人可能會說，假如程式碼寫得夠好，是不是其實不用文件? 畢竟如果程式碼寫得夠清楚，新成員直接看程式碼就能看懂，那樣有文件似乎是多此一舉?

從實務的角度來說，程式寫得好不代表可以不用文件。這是因為在維護者讀程式時，能讀到程式被怎麼寫，但是讀不到程式「為什麼這樣寫」。而技術文件的用處，很大一部分是在講解「為什麼」。

舉例來說，在技術設計文件中，要去寫相關的技術取捨，要說明為什麼選 A 技術，而不是 B 技術，背後的考量是什麼。當有了這些紀錄，未來要維護的人，不會看到程式碼時就直接說「先前的人是在幹嘛，為什麼要這樣」，而是可以透過文件，去掌握脈絡，這樣也會讓維護變得更輕鬆。

寫文件前需要先思考的問題

在開始寫作前，推薦讀者們需要先釐清一些問題，這樣才會讓寫得內容更有價值。

了解文件的讀者是誰

首先，寫作時最重要的事情，是要知道寫給誰讀。以技術文件來說，是寫給同組的工程師、寫給別組的工程師、寫給沒技術背景的產品經理，給這些不同角色時，寫的方式會很不一樣。這是因為不同讀者有的背景知識與脈絡，很可能是不同的。假如對於脈絡不熟的讀者，你寫得很簡略，對方可能看不懂；對於已經有足夠背景知識的，你再寫出這些脈絡，就顯得浪費篇幅。

如果是寫給相對缺乏技術背景的讀者，請務必確保有提及相關脈絡，這樣讀者才能懂寫得內容的重要性。舉例來說，假如在技術設計文件寫了目標是「把網頁的 LCP 優化到 1 秒內」。這句話對於不懂 1 秒內代表什麼 (例如業界基本是 2.5 秒，1.5 秒是特別優秀的表現，那這樣讀者讀到 1 秒，就知道這很不容易)。

當然，有時候讀者範圍很廣，所以補充的資訊，可以用外連的方式，放上超連結，讓有相關知識的讀者不用在文件中讀，而沒相關知識的讀者，可以透過外連去讀到。

什麼是「最重要的訊息」

在釐清完讀者是誰後，接著要想「什麼是對讀者最重要的」，或者可以思考「讀者期望從文件中獲得什麼」。

一般來說，會讀文件的人，多半是遇到問題想要找解答。所以可以回過頭思考，對方的問題是什麼? 你在解答什麼? 想清楚這點，就能更加確保寫出來的內容對讀者有價值，可以避免人家讀完後覺得浪費了自己的時間。

假如你覺得有很多資訊想傳達，有個推薦的方法，來幫助自己收斂出最重要的訊息。可以試著思考「如果只有一分鐘能跟讀者說，你會選擇說什麼?」或是「如果只能提三件事，你覺得有什麼是讀者一定要知道的?」。

透過這些問題來有效收斂，能更幫助你傳達最重要的訊息。

不同的文件有不同著重面向

前面有談到，在寫文件時，要知道是寫給誰看，以及對讀者來說什麼重要。事實上，不同類型的文件與分享，即使給相同的讀者，也可能有不同的著重面向。

具體來說，同樣是寫文件，以下三種類型文件的著重點會不同：

• 技術介紹：著重分享這個新技術是什麼 (What)，讓人快速理解某個新技術在做什麼
• 技術深掘：著重分享背後的原理，不停留在表層，會深掘為什麼 (Why)
• 專案總結：著重分享如何做到 (How)，讓未來的人不會犯同樣的錯

在寫文件時，要釐清自己是寫哪種文件，放對著重點，這樣讀者讀到的才不會與預期有出入。

閱讀更多

在談完以上的重點，接下來我們會進一步談在寫文件時要特別注意的事、避免踩到的誤區。 這些點我們在 E+ 成長計畫的主題文都有更詳細談到，推薦感興趣的讀者閱讀。

本文為 E+ 成長計畫的深度內容，截取段落開放免費閱讀。歡迎加入 E+ 成長計畫閱讀完整版本 (點此了解 E+ 的詳細介紹)。