エンジニアのオンボーディング期間を数ヶ月から数日へと短縮する方法

成長中の企業における一般的なエンジニアリングのオンボーディング体験は、およそ以下のようなものです。1週目：一部が古くなっているガイドに従って開発環境をセットアップする。依存関係の変更により手順がスキップされていることに気づくまでに2時間を費やす。Slackで質問する。誰かが返信するのを待つ。2週目：チームメンバーのシャドーイングを行い、メモを取りながらアーキテクチャについての口頭説明を聞く。理解できたのは40%程度。3週目：小さなバグ修正を割り当てられる。関連するファイルを見つけられる程度にコードベースを理解するために、週のほとんどを費やす。4週目：ようやく最初のプルリクエスト（PR）を提出する。レビューが行われ、誰も教えてくれなかった3つの規約に違反していることが判明する。

6～8週間が経過する頃、ようやく中程度の生産性を発揮できるようになります。3ヶ月経つと、ほとんどのタスクを自律的に進められるようになります。チームはこのタイムラインを普通のこととして捉えています。すべての新入社員が同じプロセスをたどるため、ドキュメントの欠如という問題ではなく、職務そのものに固有の性質であるかのように感じてしまうのです。

これはドキュメントの不足による兆候です。

オンボーディング期間を半減させるもの

研究と実務経験はいずれも一貫して同じ結論を指し示しています。エンジニアリングのオンボーディング速度に最も大きな影響を与えるのは、新入社員が利用できるドキュメントの品質と完全性です。包括的で最新のドキュメントが整備されているチームでは、オンボーディングが3～4週間で完了します。ドキュメントがないチームでは、8～12週間かかります。

その違いは、新入社員の時間がどのような活動に費やされるかにあります。ドキュメントが十分に整備されたチームでは、新入社員は最初の1週間を読み込みに費やします。システムアーキテクチャ、主要な決定とその理由、チームの規約、スタートアップガイドなどを読みます。質問は生じますが、それらは漠然とした背景に関するものではなく、具体的かつ的を絞った内容になります。ドキュメントがないチームでは、新入社員は最初の数週間を会話を通じて理解を再構築することに費やします。これは進捗が遅く、不完全であり、他のエンジニアの時間も奪うことになります。

最も重要な5つのオンボーディングドキュメント

すべてのドキュメントが等しくオンボーディングに役立つわけではありません。特にレバレッジが高いのは以下の5つです。

システムアーキテクチャの概要。 主要なサービス、それらの通信方法、およびそれぞれの役割のマップ。これにより、新入社員は個々のコンポーネントに深く入り込む前に、システム全体のメンタルモデルを構築できます。これがないと、推測や質問を重ねて数週間かけてこのモデルを構築することになり、構築されたモデルは不完全であったり間違っていたりすることがよくあります。

スタートアップガイド。 開発環境のセットアップ、プロジェクトのビルド、テストの実行、変更のデプロイを行うためのステップバイステップの手順。このガイドが節約するすべての時間は、新入社員が他の誰かに助けを求める必要のない時間となります。エンジニア以外のメンバーにこのガイドに従ってもらうことで、ガイドのテストを行ってください。もしプロジェクトを起動できなければ、ガイドに欠落している箇所があります。

意思決定の記録（Decision records）。 主要な技術的選択の背後にある明文化された理由。なぜ認証サービスがモノリスから分離されているのか。なぜこの特定のデータベースが選ばれたのか。なぜデータパイプラインにバッチ処理が採用されているのか。これらがないと、新入社員はすでに解決された問題を繰り返すミスを犯すか、チームが数ヶ月前に決定した事項の再議論に時間を費やすことになります。

チームの規約。 コーディング規約、PRレビューの期待値、コミットメッセージのフォーマット、デプロイ手順、インシデント対応プロトコル。これらは、経験豊富なチームメンバーが無意識に従っている、明文化されていないルールであり、ドキュメント化されていないと新入社員は試行錯誤しながら学ぶことになります。最初のPRレビューで指摘された、誰も教えてくれなかった3つの規約は、このドキュメントに記載されているべきです。

誰が何を所有しているか（所有権の明確化）。 チームの責任範囲、システムの所有権、特定の領域について誰に尋ねるべきかのマップ。これがあるだけで、規模を拡大中のチームを悩ませる「Xについて知っているのは誰？」という問題に費やす時間を大幅に削減できます。

オンボーディングドキュメントが古くなる理由（とその対策）

オンボーディングドキュメントの皮肉な点は、通常、新入社員が加入する前後の数週間に、すでに手一杯になっているシニアエンジニアによって場当たり的に作成されることです。ドキュメントはプレッシャーの中で作成されるため、不完全になりがちで、特定の入社社員のために作成されたものであるため、その人物が不要になった後はメンテナンスされないことがほとんどです。次の新入社員が入社する頃には、ドキュメントは部分的に古くなっており、同じサイクルが繰り返されます。

自己更新型ドキュメント（Self-writing documentation）は、チームの日々の活動から継続的にオンボーディング資料を生成することで、この状況を変えます。アーキテクチャのドキュメントは、PRや設計に関する議論から生成されるため、常に最新の状態に保たれます。意思決定の記録は、ミーティングやSlackのスレッドで決定が下されるたびにキャプチャされます。規約のドキュメントは、半年前の理想的なガイドラインではなく、実際のプラクティスを反映します。

次の新入社員が入社する時には、オンボーディング資料はすでに存在し、最新の状態に保たれています。急なドキュメント作成の時間を設ける必要も、シニアエンジニアをプロジェクトから引き離す必要も、次の四半期には古くなってしまうウィキページを急いで作成する必要もありません。

効果の測定

オンボーディングドキュメントへの投資を提案する場合、重要な指標は以下の通りです。

最初の有意義なPRまでの時間。 立ち上がりの速さを最も直接的に示す指標。ドキュメント改善の前後で、各新入社員のこの指標を追跡します。

最初の1ヶ月間に受けた質問の数。 ドキュメントがあれば解決できたはずのSlackのDMや質問をカウントします。これが大幅に減少していれば、ドキュメントが機能している証拠です。

シニアエンジニアの割り込み時間。 ドキュメントが用意される前後で、シニアエンジニアが新入社員の質問対応にどれだけの時間を費やしているかを追跡します。これは新入社員だけでなく、既存のチームにとっても恩恵を測定するものです。

自己申告による自信。 自律的にコードベースを操作できる自信がどの程度あるかを新入社員に毎週尋ねます。優れたドキュメントがあると、この曲線の立ち上がりが著しく急になります。

シニアエンジニアの給与を18万ドルから22万ドルと仮定すると、立ち上がり期間を10週間から4週間に短縮することで、新入社員1人あたり約22,000ドルから27,000ドルを節約できます。年間10人を採用する場合、自動生成可能なドキュメントによって、20万ドル以上の生産性を回収できることになります。

よくある質問

システムが複雑すぎてドキュメント化できない場合はどうすればよいですか？ ドキュメント化できないほど複雑であるならば、それは新入社員が効率的に学ぶには複雑すぎるということであり、その複雑さ自体がスケーリングのボトルネックになっていることを意味します。ドキュメント化によって、システムが何であり、どのように動作するのかを明確にせざるを得なくなります。これはドキュメントが完璧でなくても価値のあるプロセスです。まずはアーキテクチャの概要から始めて、改善を繰り返しましょう。

代わりにオンボーディングバディ（教育担当）を割り当てるべきですか？ 両方必要です。バディは、ドキュメントではカバーできない社会的・文化的なオンボーディングを提供します。ドキュメントは、会話だけでは網羅的に伝えることが難しい技術的・アーキテクチャ的なオンボーディングを提供します。バディの時間は、デプロイパイプラインの説明よりも、判断が必要な案件、紹介、文化的背景の説明に費やされるべきです。

ドキュメントを最新に保つにはどうすればよいですか？ 仕組みとしての解決策は、日々の開発アクティビティから自律的にメンテナンスされるドキュメントを採用することです。手動での解決策は、各ドキュメントにオーナーを割り当てて四半期ごとにレビューすることです。仕組みとしての解決策は、誰かがレビューを忘れることに依存しないため、より信頼性が高くなります。

関連記事：エンジニアリングオンボーディングの真のコスト、エンジニアリングチームをスケールさせる方法、ドキュメントの技術的負債。関連ページ：自己更新型ドキュメント、オンボーディングソリューション、エンジニアリングチーム向け。