文件悖論：每一次公關（PR）都讓你的文件變得不那麼準確

這是工程文檔面臨的根本問題：在你寫下它的那一刻，它就開始變得不那麼真實了。

Wiki 頁面準確地描述了撰寫當天支付服務的架構。下週，一個 PR 重構了重試邏輯。再下週，另一個 PR 添加了新的支付服務商集成。一個月後，一次重構將兩個模組合併為一個。這些更改都沒有更新 Wiki 頁面，因為代碼和文檔之間沒有任何聯繫。每個 PR 都會讓文檔的準確性降低一點，而這種偏差會隨著交付速度的加快而加速。

這就是文檔悖論：你的團隊交付得越快，你的文檔過期得就越快，這意味著最需要可靠文檔的團隊，其文檔失效的速度也最快。手動維護文檔是一場與你自身交付速度的賽跑，而且這是一場你無法獲勝的賽跑，因為文檔總是比代碼落後一步。

為什麼手動維護會失敗

面對過期文檔，標準的應對措施是建立維護流程：分配負責人、安排審查週期、將文檔更新加入 PR 檢查清單。這些流程在邊際上有所幫助，但它們都依賴於人類的自律，而這種自律恰恰在最需要文檔的情況下會退化。

當團隊在期限壓力下快速交付或處理突發事件時，文檔維護是第一個被降低優先級的事情。PR 審查人員不再檢查文檔是否已更新。Wiki 頁面的負責人在審查週期上落後了。維護流程在情況平靜時有效，而在情況緊急時失效，這意味著它在最重要的時候最不起作用。

另一個問題是，沒有人知道特定的代碼更改會影響哪些文檔。一次重構可能會使三個 Wiki 頁面、兩個架構圖和一個入職指南失效，而進行更改的工程師根本無法知道哪些文檔引用了他們正在修改的組件。即使是想要更新文檔的盡責工程師也無法可靠地做到這一點，因為代碼和文檔之間的映射關係未經維護，甚至通常根本不存在。

架構解決方案

唯一能與快速變化的代碼庫保持同步的文檔，是那些能夠從改變代碼的相同源頭中自動更新的文檔。

自動撰寫的文檔通過從即時的工程活動中生成文檔來解決這個悖論。當一個 PR 更改了兩個服務的通信方式時，關於該通信的文檔會更新以反映這一更改。當一個 Slack 對話討論並解決了一個設計問題時，相關文檔會納入該決定。當一次會議涵蓋了遷移計劃時，文檔反映的是當前的計劃，而不是三個月前的計劃。

文檔能保持最新，是因為它們是基於改變系統的相同源頭撰寫的。代碼和文檔之間沒有差距，因為文檔是源自代碼活動，而不是與代碼並行維護的。

工程師仍然會審查和完善生成的文檔，但基準準確性是自動維護的，這意味著審查是一個質量保證步驟，而不是重寫工作。悖論得到了解決，因為文檔不需要手動與一個處於變動中的目標保持同步。它們與之共同移動。

常見問題

手動維護的文檔過期有多快？ 在快速發展的團隊中，文檔撰寫後的幾週內就會出現明顯的不準確。在有著活躍開發的代碼庫中，一份有三個月歷史的文檔在細節上通常是不可靠的，即使大體框架仍然正確。

我們能只給文檔標註「最後驗證」日期嗎？ 這比什麼都不做要好，因為它給了讀者一個關於該內容可信度的信號。但它並沒有解決根本問題：仍然需要有人去驗證文檔，而這種驗證需要了解哪些代碼更改可能使其失效。

這對所有類型的文檔都是個問題嗎？ 對於描述實現細節、系統架構和集成點的文檔來說，這種情況最為嚴重，因為這些內容變動最頻繁。概念性文檔（例如我們為什麼使用微服務、我們在測試上的理念）則更持久，因為其底層決策不常改變。

相關閱讀：過期的文檔比沒有文檔更糟糕、文檔技術債、自動撰寫文檔解析。相關頁面：自動撰寫文檔、適用於工程團隊。