過時的文檔比沒有文檔更糟糕

一個沒有任何文件的團隊知道自己沒有文件。工程師會提出問題、打斷同事，並口頭重構上下文。這樣雖然效率低下，但至少每個人都清楚現狀。

一個擁有過時文件的團隊則面臨著不同的問題。文件確實存在，看起來很有權威性，但卻是錯誤的。工程師按照設定指南操作，浪費了一個下午，因為指南中引用了一個三個月前就被替換的依賴項。另一位工程師閱讀了架構概述，並據此做出了設計決策，卻在代碼審查時發現該概述描述的是一個在上季度就已重構的系統。

在經歷了兩三次這樣的體驗後，工程師便不再信任文件。他們重新回到直接詢問同事的做法，這與完全沒有文件時的情況無異。但現在，團隊除了要承擔文件原本旨在消除的口頭知識傳遞成本外，還要承擔維護無人閱讀的文件的成本。

這就是最有害的文件悖論形式：對文件的投資產生了負回報，因為文件積極地誤導了方向，而不是僅僅付之闕如。

文件是如何過時的

文件的腐爛並非因為工程師粗心大意。它的腐爛是因為每一次合併的 PR 都讓現有的文件精確度稍微降低，而修正工作卻從未被列為優先事項。

一次重構改變了兩個服務之間的通信方式。工程師更新了代碼、編寫了測試，並使 PR 通過審查並合併。更新描述舊通信模式的三個 Wiki 頁面既不在 PR 檢查清單中，也不在 Sprint 的任務中。沒有人指派這項工作，因為沒有人跟蹤哪些文件會受到哪些代碼更改的影響。Wiki 頁面就放在那裡，描述著一個已不存在的系統，等待著有人遵循它們並以失敗告終。

過時的速度與交付速度直接相關。交付速度越快，文件過時的速度就越快，這意味著最需要可靠文件的團隊（快速變動、迅速演進的代碼庫）往往也是文件腐爛最快的團隊。

信任問題

文件一旦失去信任，就極難重建。需要數十次準確、有用的文件查詢才能建立先查看文件的習慣。而只需一兩次誤導性的體驗就能將其摧毀。

一旦工程團隊集體意識到文件不可信，文件就會變得形同虛設。新員工會被非正式地告知 Wiki「大部分已過時」，他們應該直接詢問而不是閱讀。文件仍然存在，仍然出現在搜索結果中，仍然看起來很正式，但在功能上已被遺棄。花在撰寫這些文件上的每一小時都被浪費了。

唯一能避免這個問題的文件是能夠自動保持更新的文件。自動編寫的文件由即時的工程活動（PR、Slack 討論串、會議錄音）生成，並隨著底層活動的變化而更新。文件反映了現實，因為它們是基於現實編寫的，而不是與現實並行維護的。

審計問題

有一個簡單的測試可以判斷您的文件是否存在這個問題。隨機挑選一個最後更新時間在三個月之前的 Wiki 頁面或架構文件。閱讀它。然後詢問目前負責該系統的工程師，該文件是否依然準確。

在大多數團隊中，得到的答案大同小異：「部分內容是對的，但有些細節已經變了。」而正是這些細節，將會浪費下一位工程師的下午時光。

常見問題

我們應該直接刪除過時的文件嗎？ 刪除明顯過時的文件比留著它們誤導人要好。但更好的解決方案是防止過時，而不是在過時後進行清理。從即時來源自動編寫的文件不會以同樣的方式過時，因為它們會隨著底層活動的變化而更新。

我們如何知道哪些文件已經過時？ 追蹤文件最後更新的時間與它們所描述的系統最後更改的時間。如果關於身份驗證流程的文件最後一次編輯是在一月份，而自那以後驗證服務已經進行了 40 次 PR，那麼該文件幾乎可以肯定已經過時了。

如果我們交付速度很快，手動維護文件值得嗎？ 交付速度越快，手動文件過時的速度就越快，這意味著手動文件的投資回報率（ROI）隨著交付速度的提高而降低。對於快速變動的團隊來說，自動化文件是唯一能跟上步伐的方法。

延伸閱讀：文件悖論、文件債、為什麼工程師討厭寫文件。相關頁面：自動編寫文件、適用於工程團隊。