為什麼工程文檔比工程師想像的更重要

大多數工程團隊與文件之間的關係都很複雜。大家都同意它很重要，但幾乎沒有人會優先考慮它。待交付的功能清單總是顯得比待記錄的決策清單更緊急，其結果就是程式碼庫穩步增長，而對於「為什麼要這樣構建」的理解卻同樣穩步地流失。

這並非因為懶惰，而是對獎勵交付程式碼、而不獎勵編寫文件的激勵結構所做出的理性反應。然而，糟糕的文件所帶來的下游成本是真實、可衡量且遠超大多數團隊想像的，而且被忽視的時間越長，這些成本就會以更難解決的方式滾雪球般地增加。

文件的四大核心職能

工程文件發揮著四種不同的作用，而大多數團隊只考慮了其中之一。

減少錯誤。 當一個架構決策背後的推理被記錄下來時，隨後接觸該系統的工程師就能理解為什麼要這樣構建它，以及他們需要遵守哪些約束。如果缺少這個上下文，他們做出的修改在局部看起來很合理，但卻會破壞原作者所依賴的假設。這會導致難以診斷的錯誤，因為這種破壞是概念上的，而非語法上的。程式碼運行正常，但它只是做了錯誤的事情。

決策文件（即記錄為什麼選擇特定方法以及考慮了哪些替代方案的記錄）是大多數團隊所缺失的一層。程式碼註釋解釋了程式碼在做什麼。決策文件則解釋了為什麼它以這種形式存在，而不是另一種。如果沒有這個「為什麼」，每位遇到該架構決策的新工程師都會重新進行爭論。

加速入職。 加入一個文件完善的團隊的新工程師可以透過閱讀來適應環境。在編寫第一行程式碼之前，他們就能理解系統架構、關鍵決策、慣例以及當前活動項目的狀態。而加入一個文件糟糕的團隊的新工程師則必須透過交談來重建這一切，這意味著要打擾那些本應在交付成果的人。

適應時間的差異通常是數週，而非數天。而這些時間的成本，既體現在新員工效率低下的薪資上，也體現在資深工程師被打斷的生產力上。

保留組織知識。 人員會流失。他們會換團隊、換公司、休產假，或是晉升到不再接觸程式碼的職位。每一次離職都會帶走知識，而流失的知識通常是最有價值的那種：上下文、推理，以及事情為何變成現在這樣的歷史背景。

文件是將個人知識轉化為組織知識的機制，這意味著即使學習這些知識的人離開了，組織也能保留所學。如果沒有文件，組織就會不斷重新學習它已經知道的事情，這是工程領域中最昂貴的浪費形式之一。

啟用 AI 工具。 這是最近才出現的功能，且可能成為最重要的一個。您的工程工作流程中，從程式碼助手、內部代理到自動編寫文件系統的每個 AI 工具，在擁有更多上下文的情況下表現都會更好。如果您的工程知識只存在於 Slack 討論串和人們的腦袋裡，您的 AI 工具就無法存取它。文件是讓 AI 在您特定的組織背景中發揮作用，而非僅僅具備通用能力的關鍵。

為什麼文件總是輸給新功能

理解文件的重要性，並不能解釋為什麼它總是無法落實。答案是結構性的，而非文化性的。

編寫文件會產生分散的、長期的價值（下個季度更少的錯誤、下個新員工更快的入職、下個離職員工保留的知識），而交付功能則會產生集中的、立即的價值（滿足客戶需求、釋放收入、讓利益相關者滿意）。在任何權衡緊急性和可見性的優先順序框架中，新功能每一次都會勝出。因為缺少文件的代價是隱形的，直到它引起一個具體、可追溯的問題，而那時距離「不記錄」的決定往往已經過去了數月之久。

工程師們也很清楚（且沒錯），文件會過時。文件悖論在於，撰寫文件後合併的每一次公關（PR）都會讓這些文件的準確性降低一點。撰寫您知道幾週內就會過時的文件聽起來像是一個必輸的提案，對於手動維護的文件來說，確實如此。

這就是為什麼文件問題的答案是架構性的，而非激勵性的。告訴工程師多寫文件是不起作用的，因為激勵結構與此相悖。將工程師完全移出文件編寫環節，透過正在進行的工程活動（PR、Slack 討論、會議、提交（commits））自動生成並維護文件，能完全改變這種經濟學。文件之所以能保持最新，是因為它們是從源頭編寫的，而不是手動維護的。

忽略文件所帶來的複利成本

糟糕的文件成本會以與文件債相同的方式複利增加：無聲無息、累積，且比大多數團隊預期的要快。

在一個五人的團隊中，每個人都知道所有事情。整個系統都裝在少數幾個腦袋裡，部落知識行得通，因為這個「部落」很小。當達到十個人時，開始出現漏洞。達到二十人時，漏洞已明顯減緩了速度。達到五十人時，部落知識的瓶頸成為限制交付速度的主要因素之一。因為每個需要上下文的決定，都需要透過會議或 Slack 討論串來重建從未被記錄下來的上下文。

及早投資於文件的團隊很少會後悔。而將其推遲到痛苦變得劇烈時的團隊會發現，追溯性地記錄一個大型複雜系統的成本，遠高於在構建系統時就記錄它的成本。就像技術債一樣，文件債防範起來比修復起來要便宜得多。

常見問題

應該先記錄什麼？ 架構決策、系統邊界和入職指南。這些具有最高的槓桿效應，因為它們解決了最昂貴的問題：因誤解架構而產生的錯誤、緩慢的入職，以及人員流失時的知識流失。

我們如何讓工程師寫文件？ 理想情況下，您不需要這樣做。最可持續的方法是讓文件從已有的工程活動中自動生成。如果這行不通，請明確分配時間（文件衝刺、文件日），並在代碼審查（reviews）中讓文件質量變得可見。

程式碼文件（註釋、README）夠用嗎？ 程式碼文件解釋了程式碼在做什麼。它無法解釋為什麼要這樣構建系統、考慮過哪些替代方案，或者不同系統之間是如何關聯的。這兩個層面都需要，但決策和架構層通常是缺失的。

相關閱讀：撰寫工程文件的成本、文件債、為什麼工程師討厭寫文件、自動編寫文件解析。相關頁面：自動編寫文件、適合工程團隊、知識留存。