文件債的累積速度比技術債更快

工程師對技術債有著切身的體會。他們深知在充斥著累積捷徑的代碼庫中工作是什麼感覺：在當時看來，每個捷徑都是合理的，但累積起來卻讓一切變得更加困難。他們知道，事後償還技術債的代價比一開始就避免它更為昂貴，而且他們也知道，如果長期忽視它，最終將不得不進行重構。

文檔債也是如此，但有一個重要的區別：它的累積速度更快，因為沒有人在追踪它。

技術債至少在代碼本身中是部分可見的。開發人員在閱讀混亂的模塊時能感覺到債務。審查人員可以指出它。代碼規範檢查工具（linter）可以捕獲其中的一部分。而文檔債則是無形的，直到有人需要缺失的文檔並發現它並不存在時才會顯現，而到那時，事後補建文檔的成本要比一開始就創建它的成本高得多。

它是如何累積的

每一個沒有附帶相應文檔更新就發布的 PR，都會使文檔債增加一點。在 Slack 討論中做出但從未記錄在永久文檔中的每一個架構決策，都會增加更多債務。每一次口頭討論優先級和共享背景信息但從未記錄下來的會議，還會增加更多債務。

單獨來看，其中的每一次都顯得微不足道。但幾個月下來，它們共同在系統的實際運作與原創構建者之外的人對其理解之間，製造了一道鴻溝。這道鴻溝隨著每一次衝刺（sprint）而擴大，而且因為它是無形的（沒有指標追踪，沒有儀表板顯示），它在沒有人注意的情況下悄然增長，直到某個觸發事件使其痛苦地暴露出來。

這些觸發事件是可預測的：新員工需要花費數月時間才能產生生產力；核心工程師離職並帶走了關鍵的背景信息；發生生產事故時因沒有人足夠了解受影響的系統來快速診斷而導致響應緩慢；或者在架構審查中，團隊發現他們正在重新爭論一年前就已經做出並解決的決定。

為什麼它比技術債複合得更快

技術債隨著代碼的更改呈線性累積。每一個捷徑增加一個單位的債務。而文檔債則是複合增長的，因為文檔的價值是關聯性的：關於服務 A 的文檔在與服務 B 和 C 的文檔相連時才更有用，而缺失其中任何一個都會降低其他文檔的價值。

當一個系統的文檔缺失時，與之交互的系統的文檔就會變得不那麼有用，因為讀者無法順著關聯走下去。未記錄文檔的系統越多，任何單一文檔所能提供的價值就越少，因為它是孤立存在的，而不是相互關聯的整體中的一部分。

這意味著文檔債不僅僅是簡單的疊加。債務的每一次增加都會降低現有文檔的價值，這使得債務的總成本增長速度快於新債務增加的速度。當債務大到足以引起注意時，償還它的成本已經超過了大多數團隊願意投入的精力，這就是為什麼常見的反應是接受現狀並繞過它，而不是去解決它。

團隊規模的拐點

在小團隊中，文檔債是可以忍受的，因為隱性知識可以作為替代品：每個人都了解一切，因為團隊規模足夠小。拐點通常發生在 10 到 20 名工程師之間，這也是大多數團隊開始快速招聘的時期，同時也是他們最需要文檔卻最沒有時間創建文檔的時候。

這個時機是不幸但可以預見的。團隊開始增長的時刻，正是文檔變得至關重要的時刻，也正是現有團隊最疲於奔命、最無力承擔撰寫文檔等額外工作的時刻。在早期無足輕重時累積的文檔債突然變得至關重要，而償還這些債務需要將工程時間從推動增長的招聘驅動型功能開發中抽離出來。

成功度過這段轉型期的團隊，通常是那些在拐點到來之前而非之後實現文檔自動化的團隊，這樣文檔就能與團隊一同成長，而不是滯後於團隊。

常見問題

我們如何衡量文檔債？ 代理指標：新工程師入職培訓所需的時間、Slack 中提出的本可以由現有文檔（如果存在的話）回答的問題數量、重新爭論決策的頻率，以及有文檔和無文檔系統解決生產事故所需的時間。這些指標都不能直接衡量文檔債，但它們共同指示了其規模。

我們應該進行一次文檔衝刺（documentation sprint）嗎？ 文檔衝刺可以清償積壓的債務，但如果文檔的持續創建方式沒有改變，債務很快就會重新累積。這就像宣布破產：它能清空賬單，但無法改變消費習慣。結構性的解決方案是讓文檔能夠從持續的工程活動中自動生成。

團隊達到什麼規模時這會變得至關重要？ 大多數團隊在 10 到 20 名工程師之間會感受到它的影響，但債務從第一天起就開始累積。解決它的最佳時機是在你感受到它之前，因為預防的成本只是治療成本的一小部分。

相關閱讀：為什麼工程文檔至關重要、過時的文檔比沒有文檔更糟糕、文檔悖論。相關頁面：自動撰寫的文檔、適用於工程團隊。