新しく参加した開発者が最初の一週間で詰まるのは、たいていコードの外側にある。 顧客が誰なのか、検証環境の認証情報は誰に頼めば出てくるのか、四つあるリポジトリのどれから読めばよいのか。 どれもコードを読んでも分からず、聞けば五分で済むが、聞く相手が分からない。
オンボーディング文書は、この空白を埋めるために書く。
オンボーディングと呼ばれる文書には、性質の違う二つの内容が混ざりやすい。 開発環境を動かすまでの手順と、プロジェクトの背景や人の配置である。 この二つは置き場所を分ける。
環境構築手順：リポジトリに置く。 依存パッケージ、起動コマンド、環境変数の一覧は、コードと同時に変わる。 コードと離れた場所に置くと、変更したときに片方だけが古くなる。
背景と人の配置：プロジェクト単位の文書に置く。 顧客、契約のフェーズ、連絡先、開発の進め方は、どのリポジトリにも属さない。 一つのリポジトリに書けば別のリポジトリから来た人が見つけられず、全部に書けば更新のたびに同じ内容を複数箇所で直すことになる。
判定に迷ったら、リポジトリが一つ増減したときに書き換えが要るかを見る。 要らないならプロジェクト単位の情報である。
参加した人が必要とする順に並べた七項目を挙げる。
全社共通の導線と、プロジェクト固有の用語集への入口だけを置く。 全社側の内容をここに転記すると二重管理になり、食い違ったときにどちらが正しいか分からなくなる。
用語集を最初に置くのは、業務固有の語が初日の会議から出てくるためである。 意味が取れないまま議論を聞いた時間は、後から取り返せない。
誰の、どんな課題を解決するのか。 エンドユーザーは誰か。現在のフェーズは検証か、本開発か、保守運用か。 納期、納品形態、法令要件といった制約。
表紙に置く一行要約とは別に必要になる。 一行要約は索引のための機械可読な情報であり、そのプロジェクトがなぜ存在するかまでは載せられない。
チェックリストとして書き、各項目に依頼先を添える。 リポジトリへの招待、チャットのチャンネル、課題管理、共有ドライブ、検証環境の認証情報。
認証情報そのものは書かない。誰から受け取るかだけを書く。
客先環境への接続申請があるなら、所要日数を明記する。 申請から開通まで数週間かかることがあり、初日に出せたかどうかで後の工程の並び方が変わる。
アーキテクチャ文書とリポジトリ一覧へのリンクを置き、そのうえでどこから読み始めるとよいかを書く。
複数のリポジトリがある状態で順序を示さないと、いちばん行数の多いリポジトリから読み始めることになりやすい。 入口となるリポジトリを一つ指定し、その理由を一行添えるだけで足りる。
ブランチ戦略、レビューの必須人数とマージ条件、課題の起票先、リリースの承認フロー、定例の曜日と参加範囲。
全社で統一されているものは全社側に置き、ここにはプロジェクト固有の差分だけを書く。
社内の役割分担と、顧客側の窓口。 そのうえで、領域ごとに誰に聞けばよいかを書く。インフラは誰、業務仕様は誰、というかたちである。
発注者と利用者のあいだに別の組織が挟まる構造では、ここが曖昧なまま進みやすい。 障害が起きてから窓口を探すことになる。
検証環境を開いてログインしてみる程度の、手を動かす対象を一つ置く。 そのあとに読む文書として、環境構築手順、運用手順書、リンク集を並べる。
七項目すべてが最初から埋まることは少ない。 二つだけ選ぶなら、アクセス権と連絡先を先に埋める。 この二つがあれば残りが空でも初日から動けるのは、他の情報は聞けば手に入るからである。
目的と全体像だけが充実していて連絡先が空の文書は、読み物としては整っているが、参加した人を動かさない。
オンボーディング文書は、書いた時点から古くなる。 最も確実なのは、次に参加した人に直してもらうことである。 どこで詰まったかは本人にしか分からず、しかも記憶が残っているのは参加した直後の数週間だけである。
参加者への最初の依頼として、詰まった箇所をこの文書に追記してもらう運用にしておく。