開発者のオンボーディングは、たいてい入社手続きや研修が何日で終わったかで測られます。しかしそれは、問題の逆側の端を見ています。本当に意味のある数字は別のところにあります。新しく入ったエンジニアが何かを変更し、そのうえで他のどこも壊していないと自信を持って言えるようになるまでに、どれだけの時間がかかるか。多くのチームでこの数字は、日数ではなく月数で測られてしまっています。

その遅れの原因が本人にあることは、めったにありません。原因は、システムのうちどれだけの部分が他人の頭の中にしか存在していないか、そして最初の二週間のうちどれだけの時間が、それを一回の割り込みごとに少しずつ引き出す作業に費やされるか、という点にあります。

追いかける価値のある指標はひとつだけです。それは、その人の最初の変更が本番に届くまでの時間です。 最初のコミットではありません。コミットは誤字の修正でも成立してしまいます。そうではなく、意味のあった変更が実際に公開されるまでの時間です。これが一週間を超えるなら、障害になっているのはほぼ確実に本人の能力ではありません。誰も最近ゼロからやり直していないセットアップ手順か、案内なしでは入口が見つけられないコードベースのどちらかです。

開発者のオンボーディングが競合しているもの

コストは三種類あり、そのうち新しく入った人の時間はひとつだけです。

本人の時間は目に見えるコストで、誰もが最適化しようとする対象です。チームの時間は、質問のたびに別の作業をしていた誰かの手を止めるために発生し、この項目は最初のものより大きくなります。そして、ついに聞かれなかった質問のコストがあります。新しいエンジニアが、その午前中に五回目の声かけをするくらいなら自分で当て推量したほうがましだと考え、その推量が二か月後になって初めて表面化する形で間違っていた場合に生じるコストです。

良いオンボーディングが実際に取り除けるのは、この三つ目です。ドキュメントを書く価値があるのは、読むほうが聞くより速いからではありません。夜の十一時に、もう一度質問することの社会的な負担を天秤にかけずに、自分で答えにたどり着けるようにするためです。

まず環境を直す

最初の一週間の中身を最も大きく左右するのは、そのプロジェクトが誰の助けも借りずにまっさらなマシンで動くかどうかです。

チームはこの点を一貫して過小評価します。全員がすでに動く環境を持っていて、二年ほど誰も作り直していないからです。その間にセットアップ手順書のほうは古びていきます。もう存在しないバージョンを指し、去年の春に誰かが足した環境変数が抜け落ち、新しい人には一度も付与されていないサービスへのアクセスを前提にしています。データベースの初期データについては何も書かれておらず、書いた本人も、なぜ自分の手元にだけそれがあるのかを思い出せません。

直し方は地味です。次に入る人に、何ひとつ変えずに手順書をそのままなぞってもらい、つまずいた箇所をひとつ残らず記録します。その記録こそが、あなたのチームの本当のセットアップ手順です。さらに良いのは、それを一本のコマンドにまとめ、使えるテストデータを備えた動作中のシステムが、それだけで立ち上がるようにすることです。手作業の手順は、いずれ必ずずれていく手順だからです。

アクセス権も環境の一部です。コードはあってもリポジトリの権限、ステージング環境の認証情報、課題管理ツールのどれかが欠けている人は、まだ働ける状態ではありません。初日の朝に穴を見つけるのではなく、着任日より前にアカウントを用意しておきます。権限の申請ひとつが、忙しい承認者を待って丸一日を溶かすことは珍しくありません。

すぐに本物の仕事を渡す

新しい人を二週間ほど本物の仕事から守ってあげたい、という気持ちは善意から出ていますが、結果は逆になります。目的のないままコードベースを読んでも、学べることはごくわずかです。読んだ内容を結びつける先が存在しないからです。

一方、二日目か三日目に、小さくても本物で、実際にリリースできる変更をひとつ任せると、リリースまでの経路がまるごと伝わります。コードがどこにあるのか、テストはどう走るのか、レビューはどう進むのか、デプロイはどう行われるのか、そして誰に伝えればよいのか。新しいエンジニアが最も必要としているのはこの経路であり、そして、どこにも書かれていない可能性が最も高いのもこの経路です。

選ぶ対象は、実際の利用者が待っているものにしてください。作り物の練習課題ではだめです。人はその違いに気づきますし、その違いがフィードバックを真剣に受け取るかどうかを決めます。最初のレビューは早く返してください。最初の変更を二日放置することは、チームの優先順位について、教えたくない教訓を教えてしまいます。

そのうえで、隣に座って一緒に進めてください。システムを知っている人の横で過ごす一時間は、一日分の読書よりも多くを伝えます。そして横についた側も、たいていは自分のコードベースについて何か新しいことに気づきます。

書き残すもの、書き残さないもの

ドキュメントは劣化します。ですから、真であり続け、保守の手間を取り返せるものだけを書いてください。

書く価値があるもの： システムのセットアップと起動の方法、デプロイの方法、アーキテクチャの形とそれがその形である理由、書き残さなければ何度も蒸し返される決定、そして誰が何の責任を持っているか。技術ドキュメントについての解説では、保守の問題をより詳しく扱っています。

書く価値がないもの： コードがすでにはっきり述べていること、毎月変わる画面を一歩ずつたどる手順書、そして手作業で維持される網羅的なAPIリファレンス。この種の文書がいちばん早く古くなり、いちばん強く読み手を誤らせます。

多くのチームで最も価値の高い文書は、大きな部品が何であり、なぜ分けられているのかを説明する短いアーキテクチャ概要です。半日で書けて、めったに変わらず、そして新しいエンジニアが最初の一週間をかけて自力で組み立て直している、まさにその問いに答えます。図が一枚添えてあればさらに良く、その図が古びたときには、たいてい設計のほうが動いた合図になります。

オンボーディングはチームへの試験

新しい人がつまずくことは、すべて、チームがこれまで目に見えない形で吸収してきたことです。

セットアップに三日かかるなら、そのコストは前からずっとそこにあり、マシンを組み直した人全員が少しずつ払ってきただけです。ある部品がなぜ存在するのかを誰も説明できないなら、その曖昧さはとうに意思決定の質を削ってきています。デプロイの手順に特定の人物が必要なら、その依存はすでにリスクでした。技術デューデリジェンスで表に出るのも、まともな復旧計画で問題になるのも、同じ依存です。

ですから最初の数週間は、無料の監査だと考えてください。新しい人に、戸惑ったことをすべて書き留めてもらい、その一覧を本人の能力への評価ではなく、バックログとして扱ってください。それは、誰かがあなたのシステムについて書き残すもののうち、最も正直な記述です。二か月も経てば、その人もおかしさに気づかなくなるからです。

Mecanikはソフトウェア開発の仕事の一部として、既存のコードベースに定期的に加わります。つまり、他社のシステムに対してこの試験を職業として実施しているということです。立ち上がりの速いチームは、最も良いドキュメントを持っているチームではありません。最近誰かが自分の環境を作り直し、その過程で壊れたものを直したチームです。

よくある質問

開発者のオンボーディングはどれくらいの期間で終わるべきですか？ 研修の長さではなく、本番に届いた最初の意味のある変更までの時間を測ってください。それが一週間を超えるなら、障害が本人の能力であることはまれです。たいていは、誰も最近ゼロからやり直していないセットアップ手順か、案内なしでは入口が見つけられないコードベースです。

新しい開発者は最初の数日で何をすべきですか？ 実際の利用者が待っている、小さくても本物で、リリースできる変更をひとつ担当することです。目的なくコードベースを読んでも結びつける先がないため学びは少なく、一方で本物の変更をひとつ通すだけで、コードの置き場所、テストの走り方、レビューの進み方、デプロイのされ方、そして誰に伝えるかが身につきます。

環境の構築はなぜそれほど時間がかかるのですか？ 全員がすでに動く環境を持っていて、何年も誰もゼロから作っていないため、手順書が少しずつずれていくからです。直し方は、次に入る人に何も変えずにそのままなぞってもらい、失敗した箇所をすべて記録することです。その記録が本当の手順であり、一本のコマンドにまとめれば二度とずれません。

オンボーディングのために保守する価値があるドキュメントは何ですか？ システムのセットアップと起動の方法、デプロイの方法、アーキテクチャの形とその理由、書き残さなければ蒸し返される決定、そして誰が何の責任を持つかです。コードがすでに述べていること、毎月変わる画面の手順書、手書きのAPIリファレンスは省いてください。

オンボーディングが遅いことはチームについて何を示しますか？ チームが目に見えない形で吸収してきたコストが実在する、ということです。三日かかるセットアップは、マシンを組み直した全員が少しずつ払い続けてきました。誰も正当化できない部品は、とうに意思決定の質を削っています。一人しか実行できないデプロイは、新しい人が来る前からリスクでした。