工程文檔每年花費 50,000 美元。卻沒有人談論這件事。

在您的工程預算中，有一項無人會計入的成本：您的工程師花在撰寫和維護文件上的時間。它不會出現在任何專案計劃中，從未在 Sprint 規劃中進行估算，也極少在回顧會議中被討論。但它是真實存在的，而且費用高昂，對大多數團隊而言，這是部門中最大的未追蹤成本之一。

在美國，一名年薪 180,000 至 220,000 美元的資深工程師，如果計入福利和間接成本，每小時的成本大約是 85 至 105 美元。在英國，一名年薪 80,000 至 120,000 英鎊的資深工程師，在相同的計算基礎下，每小時的成本大約是 50 至 75 英鎊。

如果該工程師每週花五個小時在文件上，包括撰寫 Wiki 頁面、更新架構文件、記錄 API 變更、以長篇文字而非程式碼來解釋決策，那麼在美國，每年的成本大約在 22,000 到 27,000 美元之間。在一個由十名工程師組成的團隊中，若每人每週花三到五個小時在文件上，每年花在撰寫而非開發上的工程時間總成本將達 130,000 至 270,000 美元。

這些數字還是保守估計。它們不包括在 Slack 中解釋本應記錄在文件中的事情所花的時間，也不包括在會議中重建從未被記錄的上下文所花的時間，更不包括每次新工程師加入時回答相同入職培訓問題所花的時間。

時間實際上花在哪裡了

每週五個小時並不是一次性集中撰寫文件的時間。它分散在整週的各個小時間段中，每一次都伴隨著上下文切換的成本。

PR 後的文件編寫。 在交付重大變更後，工程師會更新 Wiki、API 文件、架構圖和任何相關的 README。對於每次重大的 PR，這可能會花費三十分鐘到一小時，但從程式碼切換到散文的上下文切換是極具消耗性的，這是單純的時間無法衡量的。

回答本應在文件中的問題。 初級工程師詢問為什麼支付服務要這樣構建。產品經理詢問數據管道是如何運作的。新員工詢問在哪裡可以找到部署指南。每個問題都要花費十到二十分鐘，而且回答往往是口頭給出，或在幾天內就會被淹沒的 Slack 對話串中。

維護現有文件。 一次重構導致三個 Wiki 頁面內容不準確。一次 API 變更使得整合指南失效。一次依賴項更新破壞了安裝說明。必須有人去尋找並修正這些問題，而這項工作非常枯燥乏味，以至於通常要等到有人遵循了過時的說明並浪費了一個下午之後，才會有人去處理。

入職培訓文件。 每次有新員工入職時，都會引發一陣撰寫文件的熱潮，因為團隊意識到，他們一直記在腦海中的東西，需要為沒有背景知識的新人寫下來。這是成本最高昂的被動式文件撰寫：在時間壓力下創建，通常不完整，且在新員工不再需要後便極少維護。

機會成本

撰寫文件的成本不僅僅是薪資工時。而是這些工時本可以用來做其他事情的代價。

資深工程師每週五個小時的時間，相當於五個小時的架構思考、程式碼審查、指導新人、偵錯或功能開發。一整年下來，對於單一工程師而言，這大約是 250 個小時，或大約六個完整的工時週，從他們當初被僱用來做的工作中被轉移了出來。

對機會成本感受最深的通常是最資深的工程師，因為他們擁有最多需要記錄的背景知識，且他們的時間也有著最有價值的其他用途。文件撰寫的負擔最沉重地落在組織最無法承受其分心的關鍵人才身上。

替代方案

上述成本計算假設撰寫文件需要人工工程時間，自軟體工程存在以來，這一點一直都是成立的。而自動撰寫文件技術改變了這一假設。

當文件能夠從現有的工程活動中自動生成並維護，例如目前以暫存形式保存您知識的來源（GitHub 的 PR 和 Commit、Slack 對話、會議錄音、設計文件），人工撰寫的成本就會降到接近於零。

工程師仍然會審查生成的的文件，修正不準確之處，並添加自動化系統遺漏的背景資訊。但是，將組織活動轉換為結構化、可搜尋文件的基礎工作，改由系統處理，而不是由那些時間成本為每小時 85 至 105 美元的人來做。

對於一個由十名工程師組成、每人每週花五個小時在文件上的團隊來說，即使只消除 80% 的手動工作，每年也能省下 100,000 至 215,000 美元的工程時間。這相當於多聘用了一名工程師，而資金完全來自於不浪費您現有工程師的時間。

常見問題

每週五個小時是切合實際的嗎？ 對工程團隊的調查一致顯示，資深工程師每週撰寫文件的時間為四到八個小時，在入職培訓期間和重大重構後，這個數字還會上升。五個小時是一個保守的估計，許多團隊一旦開始追蹤，會發現其實際數字更高。

那些根本不寫文件的團隊呢？ 他們以不同的方式支付這筆成本：透過更長的入職培訓時間、對資深工程師的更多打擾、因誤解架構而產生的更多錯誤，以及人員離職時更多的知識流失。不寫文件的成本往往高於寫文件的成本，它只是不那麼顯眼，因為它分散在數十個微小的效率低落之處，而不是以單一預算項目的形式出現。

如何計算您自己團隊的成本？ 計算工程師的人數，估算他們每週在文件相關活動（撰寫、維護、回答本應在文件中的問題）上花費的平均小時數，乘以他們包含福利的每小時成本。大多數團隊一旦實際計算，會發現這個數字大得令人吃驚。

相關閱讀：為什麼工程文件至關重要、為什麼工程師討厭寫文件、糟糕的文件讓您付出了多少代價？。相關頁面：自動撰寫文件、適合工程團隊。