ExplainThis 全端開發雙週報 #52

工程師如何寫好文件

嗨～ 歡迎閱讀第 52 期的 ExplainThis 全端雙週報。

在進到這期的主題文之前，想分享 ExplainThis 正式上架了《給工程師的 Cursor 工作流 — 透過 AI 代理全方位提升開發生產力》線上課程的教材到 ExplainThis 的網站，讓想了解如何高效使用 Cursor 的讀者們可以免費閱讀 (連結)。

如果偏好看影片的讀者，歡迎加入 E+ 成長計畫 (連結)。雖然這門課是以 Cursor 做為主要工具，但課程中講到的概念，都適用其他 AI 驅動的工具 (例如 Windsurf 或 GitHub Copilot)。

以上，讓我們進到這期的雙週報主題文吧～

工程師如何寫好文件

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

從個人的角度來看，對個人而言寫好文件的槓桿很高，因為寫文件時，能幫助自己想得更清楚，且文件本身是種擴大影響力的媒介。對團隊與公司來說，寫文件的好處也很多，確保關鍵知識不會遺失，以及透過文件讓新團隊成員可以獨立運作，並讓資深成員的時間可以被釋放。

要能夠寫好文件，推薦在開始寫作前，讀者們先問一些釐清的問題，確保寫得內容是有價值的。

了解文件的讀者是誰

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

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

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

什麼是「最重要的訊息」

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

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

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

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

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

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

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

• 技術介紹：著重分享這個新技術是什麼 (What)，讓人快速理解某個新技術在做什麼

• 技術深掘：著重分享背後的原理，不停留在表層，會深掘為什麼 (Why)

• 專案總結：著重分享如何做到 (How)，讓未來的人不會犯同樣的錯

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

在思考完讀者是誰、什麼是最需要被傳達的概念後，接著就可以開始寫文件了。在實際撰寫文件時，有一些要點，是推薦讀者們可以參考的。詳細的內容，我們在 E+ 成長計畫的主題文有談到，感興趣的讀者，歡迎加入 E+，一起成長 (連結)

本期推薦

• 上週在社群看到很多人轉貼，一個大學生在推特上展示自己的成果，然後被 Shopify 的 COO 看到，於是開了一個原本 Shopify 沒有的實習缺給這名大學生。雖然這不是工程師的求職，但概念很相似，如果成果夠好，展示出來就有可能讓公司去開出本來不存在的職缺 (連結)

• 先前 ExplainThis 曾寫過《How to work with me》文件的相關介紹 (連結)，推薦每個人在工作上要寫一份。最近看到 OpenAI 產品長分享 DoorDash 的 Keith Yandell 寫的版本，非常有啟發性 (連結)

• 在開源社群很活躍的Matthias Endler最近分享了《The Best Programmers I Know》，談到在他的開發生涯中，見過最棒的開發者有哪些共同的特質，有志成為更優秀工程師的讀者，可以比對看看自己還有哪些面向能做更好 (連結)

• 這週社群上廣傳了 Aaron Swartz 當年寫的《Theory of Change》一文，該篇文章之所以是經典，是因為點出了許多人在往目標邁進時，忽略了由目標往回推的分析 (連結)

• 《Web Components in Earnest》一文中實作顏色選擇器，深入到非常細節之處，寫得很精彩，如果對於這種深入前端實作分析感興趣的讀者，推薦一讀 (連結)

• Acquired Podcast 最新一集談到醫療軟體公司 Epic Systems，故事非常精彩。Epic Systems 的公司運作方式與大家熟知的矽谷式軟體公司，有很大的不同，但同時從各角度衡量都非常成功 (連結)。也許大家在選擇工作時，可以用更多元的角度來評估，過去我們寫過《選一間冷靜的公司》是另一種角度 (連結)

文末彩蛋

上週讀到組織心理學家 Adam Grant 分享的一段話 (連結)，他談到要成為讓人覺得可信的人，最有力的訊號不是知道多少，而是多在乎準確性。追求準確意味著背後沒有隱藏的意圖，即使事實與自己期望相左，也會堅持追求事實。

這句話對於軟體工程師尤其重要。雖然常說在軟體的領域沒有所謂的對錯，但近期越來越多新技術在推出時，有過多的包裝；在社群中許多對技術的討論，也有不少「用某某技術就是好，用另個技術就是不好」但缺乏證據支持的觀點。

Adam Grant 也提到想要變得更可靠，持續學習是最關鍵的。願我們都能以精確為目標看待任何技術，同時期望 ExplainThis 的內容能持續協助讀者們在職涯上，成爲更加可靠的開發者。

The strongest signal of credibility is not how much people know. It's how much they care about accuracy. Trustworthy sources don't have an agenda. They pursue the truth even if it counters their hopes and beliefs. The most reliable voices are the ones most invested in learning.

— Adam Grant