一名新工程師在適應期每個月花費 15,000 美元。而文件能將這筆成本減半。

新入職的工程師從第一天起就需要全額支付薪資，但在適應期內產出幾乎為零。以美國資深工程師 180,000 至 220,000 美元的年薪計算，每月含福利的綜合成本大約在 15,000 至 18,000 美元之間。在該工程師閱讀代碼、提出問題、參加系統講解以及普遍吸收背景資訊，而非交付成果的幾週內，公司正在以全額的代價換取極小部分的產出。

這完全是正常且符合預期的。問題不在於是否有適應期，而是在於適應期持續多久，而縮短適應期最關鍵的槓桿，就是新員工可以獲取的技術文檔質量。

技術文檔帶來的差異

在一個擁有完善、最新文檔的團隊中，新工程師的第一週通常是這樣的：閱讀架構概述，理解核心系統及其交互方式，查閱有關重大技術選擇的決策日誌，按照入門指南操作，並部署一個微小的變更。他們雖然會有疑問，但許多問題已經在文檔中得到了解答，剩下的問題也是具體且有針對性的，而非寬泛的背景詢問。

在一個缺乏文檔的團隊中，同一位工程師的第一週景象則截然不同：必須找一個願意帶他們了解系統的人，從口頭概述中努力吸收那些必然不完整的資訊，在一個部分有記錄、部分靠四處打聽的配置流程中跌跌撞撞，並花費大量時間去弄清楚不僅是系統本身，還有哪些部分該去問誰。

對於文檔完善的團隊，適應期通常為四到六週，而文檔匱乏的團隊則需要八到十二週。以每月 15,000 至 18,000 美元計算，將適應期從十週縮短到四週，每招募一名員工就能節省 22,500 至 27,000 美元。

以一家處於增長階段的初創公司每年招募十名工程師計算，這相當於挽回了 225,000 至 270,000 美元的生產力。對於每年招募二十名或更多工程師的大型組織，節省的成本更會按比例遞增。

優秀的入職培訓文檔應包含哪些內容

並非所有文檔對入職培訓都有相同的幫助。投資回報率最高的入職培訓文檔包括：

系統架構概述。 一張展示主要服務、它們如何通信以及各自職責的圖譜。這能讓新員工在深入研究任何單一組件之前，對整個系統有一個全局的心理模型。

入門指南。 關於配置開發環境、構建項目、運行測試和部署變更的逐步說明。入門指南每節省一分鐘，新員工就少花一分鐘去向他人求助。

核心決策及其緣由。 解釋系統為何如此構建的決策記錄。如果沒有這些，新員工要麼會犯下重複已知問題的錯誤，要麼會花費時間重新爭論已經做出的決定。

團隊規範。 編碼標準、PR 審查預期、部署流程、事件響應協議。這些是資深團隊成員潛意識裡遵循的成文或不成文規則，若沒有文檔記錄，新員工就只能通過反覆試錯來學習。

職責分工。 團隊職責、系統所有權以及特定領域該諮詢誰的對照表。光是這一項，就能為新員工節省數小時通過試錯來摸索團隊結構的時間。

自動生成的入職文檔

入職培訓文檔的諷刺之處在於，它通常是由本就極度繁忙的資深工程師，在新員工加入前後的幾週內被動創建的。這些文檔是在時間壓力下草成，且因其是為特定新人創建，在該新人不再需要後，往往就無人維護了。

自動生成文檔改變了這種經濟效益，它能從團隊的日常活動中持續生成入職培訓材料。架構文檔始終保持最新，因為它是從 PR 和設計討論中自動生成的。決策記錄在做出決策時即被捕獲。規範文檔反映的是實際實踐，而非流於形式的願景指引。

當下一位新員工加入時，入職培訓材料早已存在且保持最新。無需臨時衝刺撰寫文檔，無需將資深工程師從其核心項目中抽離，也無需急就那些到下個季度就會過期的 Wiki 頁面。

常見問題解答

如何衡量改善入職文檔的投資回報率（ROI）？ 追蹤新員工在改進文檔前後，提交第一個有意義的 PR（或第一次生產環境部署）所需的時間。這是衡量適應期最直接的指標。同時也追蹤新員工在第一個月內提出的問題數量，當有優秀文檔支持時，這個數量通常會顯著下降。

最重要、應該最先創建的入職文檔是什麼？ 系統架構概述和入門指南。兩者結合解決了新員工最緊迫的需求：理解系統做什麼，以及讓系統在本地運行起來。

這是否也適用於承包商和自由職業者？ 更是如此，因為承包商的合作期限通常較短，且對冗長適應期的容忍度更低。優秀的文檔能讓承包商在幾天內而非幾週內產生生產力，這意味著組織能從合作中獲得更大的價值。

延伸閱讀： 巴士係數（The bus factor）、隱形知識的隱性成本、文檔債務。相關頁面： 自動生成文檔、入職培訓、專為工程團隊打造。