新人エンジニアが立ち上がるまでのコストは月額1万5,000ドルにのぼります。ドキュメントがあれば、そのコストを半分に削減できます。

新しく採用されたエンジニアは、立ち上がり期間中に出力がほぼゼロであるにもかかわらず、初日から満額の給与コストが発生します。米国のシニアエンジニアの給与を180,000ドル〜220,000ドルとすると、各種手当や社会保険などを含めた月額コストはおよそ15,000ドル〜18,000ドルになります。そのエンジニアがコードを読み、質問をし、ウォークスルーに参加し、全体としてコードをリリースするよりもコンテキストを吸収している数週間、会社はごくわずかな成果に対して満額の費用を支払っていることになります。

これは完全に正常であり、想定内のことです。問題は立ち上がり期間があるかどうかではなく、それがどれだけ続くかであり、立ち上がり期間に最も大きな影響を与える唯一の要因は、新しいメンバーがアクセスできるドキュメントの品質です。

ドキュメントによる違い

包括的で最新のドキュメントがあるチームでは、新メンバーの最初の1週間は次のようになります：アーキテクチャの概要を読み、主要なシステムとそれらがどのように相互作用するかを理解し、主要な技術的選択に関する意思決定ログを確認し、セットアップガイドに従い、小さな変更をデプロイする。質問は生じますが、その多くはドキュメントによって解決され、残る質問は広範で状況把握的なものではなく、具体的で的を絞ったものになります。

ドキュメントのないチームでは、同じエンジニアの最初の1週間は異なります：システムについて説明してくれる人を探し、不完全になりがちな口頭の概要から理解できる限りのことを吸収し、一部のみドキュメント化され、一部は周囲への質問に依存しているセットアッププロセスを何とか進め、システムだけでなく、どの部分について誰に尋ねればよいかを理解するのにかなりの時間を費やします。

立ち上がり期間の差は、一般的に、十分にドキュメント化されたチームでは4〜6週間であるのに対し、ドキュメント化が不十分なチームでは8〜12週間になります。月額15,000ドル〜18,000ドルのコストを考えると、立ち上がり期間を10週間から4週間に短縮することで、1人の採用あたり22,500ドル〜27,000ドルを節約できます。

成長中のスタートアップで一般的な、年に10人のエンジニアを採用する場合、回収される生産性は225,000ドル〜270,000ドルになります。年間20人以上のエンジニアを採用する大企業の場合、節約額は比例して大きくなります。

優れたオンボーディングドキュメントの内容

すべてのドキュメントがオンボーディングに同じように役立つわけではありません。最も効果の高いオンボーディングドキュメントは以下の通りです：

システムアーキテクチャの概要。 主要なサービス、それらの通信方法、およびそれぞれが何を担当しているかのマップ。これにより、新メンバーは個々のコンポーネントを詳しく掘り下げる前に、システム全体のメンタルモデルを構築できます。

スタートアップガイド。 開発環境のセットアップ、プロジェクトのビルド、テストの実行、および変更のデプロイを行うためのステップバイステップの手順。セットアップガイドが節約するすべての時間は、新メンバーが他の誰かに助けを求める時間を減らすことにつながります。

主要な意思決定とその理由。 システムがなぜそのように構築されているかを説明する意思決定記録。これらがなければ、新メンバーは解決済みの問題を繰り返すような過ちを犯すか、すでに決定された事項を再び議論することに時間を費やすことになります。

チームの慣習。 コーディング基準、PRレビューの期待値、デプロイ手順、障害対応プロトコル。経験豊富なチームメンバーが意識せずに従っている、ドキュメント化されていないために新メンバーが試行錯誤して学ぶ不文律です。

誰が何をやるか。 チームの責任範囲、システムの所有権、特定の領域について誰に質問すべきかのマップ。これだけで、新メンバーが試行錯誤しながらチーム体制を把握するために費やすはずだった時間を何時間も節約できます。

自己記述型オンボーディングドキュメント

オンボーディングドキュメントの皮肉な点は、通常、新メンバーが参加する前後の数週間に、すでに最も多忙を極めているシニアエンジニアによってリアクティブに作成されることです。ドキュメントは時間のプレッシャーの下で作成され、特定の採用者のために作成されるため、そのメンバーがドキュメントを必要としなくなった後は維持されないことがよくあります。

自己記述型ドキュメントは、チームの継続的な活動からオンボーディング資料を継続的に生成することで、この経済性を変化させます。アーキテクチャドキュメントは、PRや設計の議論から生成されるため、常に最新の状態に保たれます。意思決定記録は、意思決定が行われると同時に記録されます。慣習ドキュメントは、形骸化したガイドラインではなく、実際のプラクティスを反映します。

次の新メンバーが参加するときには、オンボーディング資料はすでに存在し、最新の状態に保たれています。ドキュメント作成のためのスプリントも、シニアエンジニアをプロジェクトから引き離すことも、次の四半期には古くなってしまうような急造のWikiページを作成することも必要ありません。

よくある質問

より優れたオンボーディングドキュメントのROIはどのように測定しますか？ 新メンバーがドキュメントを改善する前と後で、最初の意味のあるPR（または最初の本番環境へのデプロイ）までの時間を追跡します。これが立ち上がり期間の最も直接的な指標です。また、最初の1ヶ月間に新メンバーが質問した回数も追跡します。優れたドキュメントがある場合、この回数は大幅に減少する傾向があります。

最初に作成すべき最も重要なオンボーディングドキュメントは何ですか？ システムアーキテクチャの概要とスタートアップガイドです。これらは、新メンバーの最も差し迫ったニーズ、すなわちシステムが何を行うかを理解し、それをローカルで実行することに対応します。

これはコントラクターやフリーランスにも当てはまりますか？ コントラクターは通常、契約期間が短く、長い立ち上がり期間が許容されないため、なおさら当てはまります。優れたドキュメントがあれば、コントラクターは数週間ではなく数日で生産性を発揮できるようになり、組織はその契約からより多くの価値を得ることができます。

関連する読み物：バス係数、暗黙知の隠れたコスト、ドキュメントの技術的負債。関連ページ：自己記述型ドキュメント、オンボーディング、開発チーム向け。