如何將工程團隊的入職培訓期從幾個月縮短至幾天

在一家成長型公司中，典型的工程入職體驗大約是這樣的。第一週：使用一份部分過時的指南來設定你的開發環境。花兩個小時才發現因為依賴項改變而跳過了一個步驟。在 Slack 上發問。等待有人回覆。第二週：跟隨團隊中的某個人，在你想辦法做筆記的同時，他口頭向你解釋系統架構。大概只能聽懂 40%。第三週：被指派一個修復小 Bug 的任務。這週的大部分時間都花在了解程式碼庫上，以便找到相關檔案。第四週：終於提交了你的第一個 PR。經過審查後，你才得知自己違反了三個沒人告訴過你的規範。

到了第六到第八週，你開始有中等程度的產出。三個月後，你已經能獨立處理大部分工作。團隊認為這個時程很正常，因為每個新員工都是如此，這讓人覺得這是該職位固有的挑戰，而不是缺乏文件所導致的症狀。

這其實就是缺乏文件所導致的症狀。

是什麼讓入職時間縮短了一半

研究和實際經驗一致指出同一個結論：影響工程入職速度的最大單一槓桿，就是提供給新員工的文件品質和完整性。擁有全面且即時文件的團隊，入職時間只需三到四週。而缺乏文件的團隊則需要八到十二週。

其差異在於新員工的時間花在哪些活動上。在一個文件完善的團隊中，新員工第一週的時間都花在閱讀上：系統架構、關鍵決策及其原因、團隊規範、新手指南。他們會有問題，但這些問題是具體且有針對性的，而不是廣泛且需要補足背景脈絡的。在一個缺乏文件的團隊中，新員工在最初幾週必須透過與人交談來重建這些理解，這不僅速度較慢、不夠完整，而且還會消耗其他工程師的時間。

最重要的五份入職文件

並非所有文件對入職的幫助都一樣。這五份文件的槓桿作用最高。

系統架構概覽。 一張主要服務、它們如何通信以及各自負責什麼的架構圖。這能讓新員工在深入任何組件之前，先建立起整個系統的心智模型。如果沒有它，他們會花費數週時間透過推論和提問來建立這個模型，而且建立的模型往往是不完整或錯誤的。

新手指南。 逐步說明如何設定開發環境、建置專案、執行測試以及部署變更。這份指南每省下一分鐘，新員工就少花一分鐘去向其他人尋求協助。可以透過讓非工程人員照著操作來測試這份指南。如果他們無法讓專案順利運行，就說明指南中存在漏洞。

決策記錄。 記錄關鍵技術選擇背後的推理過程。為什麼驗證服務與單體架構分離。為什麼選擇這個特定的資料庫。為什麼數據管道使用批次處理。如果沒有這些記錄，新員工要麼會犯下重複已解決問題的錯誤，要麼會花時間重新討論團隊在幾個月前就已做出的決定。

團隊規範。 編碼標準、PR 審查預期、Commit 訊息格式、部署程序、事件響應協定。這些是資深團隊成員在潛意識中遵守的成文或未成文規則，而當它們沒有被寫下來時，新員工只能通過反覆試錯來學習。那些在新員工的第一個 PR 審查中被指出、但之前根本沒人告訴過新員工的三個規範？它們應該被寫在這份文件中。

誰負責什麼。 一份包含團隊職責、系統所有權以及特定領域該向誰請教的對照表。光是這一點就能省去困擾擴張中團隊的「誰了解某個技術？」的問題。

為什麼入職文件會過時（以及如何解決）

入職文件最諷刺的地方在於，它通常是在新員工加入前或加入後的幾週內，由那些已經最為忙碌的資深工程師被動建立的。這些文件是在壓力下建立的，通常不完整，而且因為是為特定員工建立的，一旦該員工不再需要，就很少會有人去維護。等到下一個員工加入時，文件已經部分過時，如此循環往復。

自動生成的自撰寫文件改變了這一現狀，它能從團隊持續進行的活動中，不間斷地產生入職資料。架構文件之所以能保持最新，是因為它是從 PR 和設計討論中自動生成的。決策記錄是在會議和 Slack 討論串中做出決策時即時擷取的。規範文件反映的是實際的做法，而不是半年前那些流於形式的指導方針。

當下一個新員工加入時，入職資料早已存在且保持最新。不需要在衝刺階段趕工寫文件，不需要把資深工程師從他們的專案中抽離，也不需要匆忙趕出下個季度就會過時的 Wiki 頁面。

評估成效

如果你想說服大家投資入職文件，以下是幾個關鍵的衡量指標。

首次提交有意義 PR 的時間。 這是評估上手速度最直接的指標。在改進文件前後，追踪每位新員工的這項數據。

第一個月提出的問題數量。 統計那些本可以透過文件解答的 Slack 私訊和提問。數值顯著下降代表文件發揮了作用。

資深工程師被打斷的時間。 追踪在文件建立前後，資深工程師花在回答新員工問題上的時間。這衡量了文檔對現有團隊的效益，而不僅僅是對新員工的幫助。

自我評估的信心度。 每週詢問新員工他們在獨立巡覽程式碼庫時感到多有信心。在有良好文件支持的情況下，這條信心曲線的坡度會明顯變陡。

以資深工程師 180,000 至 220,000 美元的年薪計算，將上手時間從十週縮短到四週，每位新員工大約可節省 22,000 至 27,000 美元。以每年招募十名新員工計算，這相當於回收了超過 200,000 美元的生產力，而這完全可以透過自動生成的技術文件來實現。

常見問題

如果我們的系統太複雜而無法記錄怎麼辦？ 如果系統複雜到無法記錄，那麼對於新員工來說就太複雜了，無法高效學習，這意味著複雜性本身就是擴充的瓶頸。撰寫文件能強迫大家釐清系統是什麼以及它是如何運行的，即使文件不夠完美，這也很有價值。先從架構概覽開始，然後逐步疊代。

我們是不是應該指派一個入職夥伴（Onboarding Buddy）代替？ 兩者都需要。夥伴能提供文件無法提供的社交和文化融入。而文件則能提供夥伴無法在日常交談中全面傳授的技術和架構引導。夥伴的時間更應該花在判斷決策、介紹引薦和文化背景的建立上，而不是花在解釋部署管道上。

我們該如何保持文件最新？ 系統性的解決方案是採用能根據日常工程活動自我維護的文件。手動的解決方案是為每份文件指定負責人，並進行每季審查。系統性的解決方案更可靠，因為它不依賴於是否有人記得去進行審查。

延伸閱讀：工程入職的真實成本、如何擴展工程團隊、文件債。相關頁面：自動撰寫文件、入職解決方案、適用於工程團隊。