優秀的文檔是十倍的工程效益倍增器

撰寫文件通常被認為是為了解決讀者的需求：新員工、初級工程師，或是正在不熟悉程式碼庫區域工作的同事。這固然是事實，但如果只關注方程式的這一端，就大大低估了文件的價值。

更顯著的好處，其實是讓那些不再被打擾的人受益。

中斷的代價

處理複雜問題的資深工程師需要持續專注。關於情境切換的研究一致顯示，一次中斷（即使是短暫的中斷）所付出的代價，遠超過中斷本身持續的時間。Gloria Mark 的研究指出，在中斷之後，大約需要 25 分鐘 才能恢復到先前的專注程度。

一位資深工程師如果一天因原本能透過良好文件解答的問題被打斷十次，他損失的不僅僅是解答的十分鐘，還包括因恢復專注而損失的大約四個小時的高效專注時間。這相當於半個工作天就因為缺乏文件而耗盡了，而且工程師往往意識不到發生了什麼，因為每次單獨的中斷看起來都很短暫且容易應付。

這些問題本身完全合理。「為什麼驗證服務要這樣架構？」、「哪裡可以找到部署指南？」、「使用這個佇列而不是資料庫的原因是什麼？」、「數據管道如何處理失敗的記錄？」每一個問題都有答案。在沒有文件的團隊中，答案只存在於資深工程師的腦海中，只能透過打斷他們來獲取。

乘數效應

良好的文件會產生乘數效應，並隨著團隊規模的擴大而增長。

在五個人的團隊中，中斷是可控的，因為團隊規模小且共享背景資訊。但在一個擁有五位資深工程師和十五位需要經常向他們獲取背景資訊的二十人團隊中，中斷負載呈非線性增長。每位資深工程師現在都成了三到四個人提問的瓶頸，這對資深工程師生產力造成的總成本是巨大的。

文件打破了這個瓶頸，它讓資深工程師的知識在不需要佔用他們注意力的情況下變得唾手可得。初級工程師可以閱讀架構文件而不是發問。新員工可以遵循入職指南而不是要求手把手教學。而在不熟悉的程式碼庫區域工作的同事，可以閱讀 決策日誌 而不是安排會議。

每一個從問人轉向查閱文件的問題，都節省了提問者的等待時間和解答者的中斷成本。在全團隊每天十個問題的規模下，這能節省二到四個小時的資深工程師時間，這相當於多出了一位專門透過代理回答問題的資深工程師。

誰最受益

從良好文件中受益最多的，通常是團隊中最資深、最有價值的工程師，也就是那些時間最寶貴、專注力最關鍵的人。然而，當需要手動撰寫文件時，這些人也是承擔 最大文件負擔 的人，這創造了一種特別浪費的動態：專注力最有價值的人最常被打斷，而解決方案（撰寫文件）也落到他們身上，消耗了更多本該受到保護的專注力。

自動生成文件 解決了這個惡性循環，它能從資深工程師現有的產出（他們的 PR 描述、他們的 Slack 說明、他們的 會議貢獻）中自動生成文件，而不需要他們做額外的工作。他們已經在特定情境下分享的知識會被捕獲並結構化，因此任何人都可以在任何時間找到它，而不會打斷知識的源頭。

常見問題

我們如何衡量中斷成本？ 記錄一週內資深工程師透過 Slack 私訊和面對面請求收到的問題數量。乘以 25 分鐘（每次中斷的平均恢復成本），即可得出失去的總專注時間。大多數團隊會發現這個數字遠比他們預期的要高。

初級工程師會不會根本不看文件？ 如果文件是最新、組織良好且可搜尋的，採用率通常很高，因為另一種選擇（等待資深工程師回覆）更慢。如果文件是 陳舊且不可信的，不論如何工程師都不會去看。文件的品質決定了採用率。

這能證明購買文件工具的成本是合理的嗎？ 以資深工程師的薪資來算，在一個小團隊中每週只要回收兩小時的專注時間，通常就超過了市場上任何文件工具的成本。投資報酬率的計算幾乎總是正向的，而且好處會隨著團隊規模的擴大而增長。

延伸閱讀：為什麼工程文件很重要、撰寫工程文件的成本、部落知識（Tribal Knowledge）的隱形阻礙。相關頁面：自動生成文件、適用於工程團隊。