Helper CTO シリーズ 17｜引き継ぎをブラックボックスにしない：次の人に残せる最小限のドキュメントセット

「ドキュメント？辞めるときに『全部コードに書いてある』と言われました」。この言葉のツケは、次のエンジニアが入社した最初の週に具体的な形で現れます。彼はこのシステムがどう動いているのかを推測するのに3日を費やし、その3日間にシステムに何か起きても、対処できる人が誰もいません。あなたはドキュメントを軽視しているわけではなく、最低限何が必要かを誰も教えてくれなかっただけです。以下の5つを、それぞれ1ページ以内でまとめます。

ドキュメントがなければ、引き継ぎは発掘調査になる

発掘調査とは、新しく来た人が何日もかけてこのシステムがどう動くのか推測し、推測しながら試し、その失敗のツケをあなたが払うということです。彼が推測しなければならないのは次のことです。

• サーバーがどのプラットフォームで、どのアカウントでログインし、毎月の請求は誰が払っているか。
• ドメインは誰の名義で登録されていて、いつ期限切れになり、更新は誰が担当しているか。
• データベースのパスワードがどこにあり、バックアップが本当に動いているかどうか。
• デプロイが手動か自動か、前回成功したデプロイはいつか。
• どのサードパーティサービスがまだ課金されていて、どれがもう使われていないか。

さらに厄介なのは、推測できないものがあることです。旧担当エンジニアのパソコンに残っていたデプロイコマンドや、本人しか知らないログイン方法は、書き残されていなければ消えてしまいます。

最小限のドキュメントセット：5つ、それぞれ1ページ

分厚い技術仕様書は必要ありません。そういうものは誰も更新しません。必要なのは、このシステムを見たことのないエンジニアが1日で対応できるようになる5枚の紙です。

5つ合わせても5ページを超えません。これは「明日から来るエンジニア」のために書くものであって、自分用のメモではないことを忘れないでください。

5つのうち、先にどの2つを書くか

5つを一度に書き切れない場合は、まずこの2つを書きましょう。残りの3つはゆっくり補えばいいです。

• どうデプロイするか：この作業が今1人にしかできないなら、それがシステム全体で最も脆弱な部分です。手順を書き出しましょう。どこからコードを取得するか、何を実行するか、成功をどう確認するか、失敗したら前のバージョンにどう戻すか。
• 誰がログインできるか：アカウント権限が整理されていないと、辞めた人がまだ入れる可能性があります。このページには「パスワードの入手先」だけを書き、パスワード自体はパスワード管理ツールに入れておきます。
• この2つは会議なしで書き終えられます：それぞれ1ページ、午後の数時間で初版ができ、残りの3つは後で補えます。

「ものを取り戻す」ことと「ものを書き残す」ことは、一緒にやるべき2つの作業です。エンジニア退職後にまず取り戻すべき12のものの記事が扱うのは前者です。私たちがシステムを引き継ぐ最初の1か月（引き継ぎ後の最初の1か月に私たちがすることを参照）では、1週目に作成する「現状マップ」がこの5つの初版になります。

陳腐化させない方法

ドキュメントの最大の敵は「書かれていないこと」ではなく、「書かれたのに誰も更新せず、半年後には現状と合わなくなり、かえって次の人を誤らせること」です。3つの方法があります。

• 変更と一緒に更新する：サーバーを変えたり、サービスを追加したり、デプロイ方法を変えたりするたびに、その変更の一部としてそのページも直接更新します。
• 四半期ごとに見直す：セキュリティアップデートと合わせて行います。セキュリティアップデートは四半期に最低1回行うので、そのついでに5ページを見直します。
• みんなが見つけられる場所に置く：コードと一緒に置くか、会社の共有スペースに置きます。誰かの個人用ハードディスクに置くのは、存在しないのと同じです。

ドキュメントが生きているかどうかを判断するのは簡単です。「担当者が1週間休んだら、誰かがこの5ページを見てシステムを維持できるか」と自問してください。答えが「いいえ」なら、更新すべき時です。

契約終了時にこれらをお渡しする理由

多くのベンダーはドキュメントを残しません。その理由を正直に言えば、ドキュメントが少ないほど顧客が離れられなくなるからです。私たちのやり方はその逆で、理由もきわめて実際的です。

• 私たちは月単位で請求しており、いつでも止められます。「あなたが離れられない」状態に頼るビジネスモデルは成り立ちません。
• 頼れるものは1つだけです。毎月、このお金を払う価値があると感じてもらえるかどうかです。
• ドキュメントをお渡しすることで、あなたに選択肢が生まれます。選択肢があったうえで残ってもらえて初めて、本当の意味での協力関係です。

引き継ぎで気をつけるべきその他の詳細は、システム運用引き継ぎガイドの記事に完全なチェックリストがあります。

Nerdtechnicがお渡しする、その5ページ

• 最初の1か月で5つとも書き上げる：引き継ぎ最初の週に初版を作成します。契約終了時になって慌てて補うことはありません。
• 変更のたびに更新する：サーバーの変更、サービスの追加、デプロイ方法の変更、対応するページはその日のうちに更新します。
• 四半期ごとにセキュリティアップデートと合わせて見直す：四半期に最低1回、5ページを現状と照らし合わせます。
• 契約終了時にすべてお渡しする：ドキュメントと記録はすべてあなたのものです。担当者が変わってもブラックボックスにはなりません。

ドキュメントの価値は、どれだけきれいに書かれているかではなく、いつでも担当者を交代できるかどうかにあります。

引き継ぎをブラックボックスにしないために必要なのは、分厚いマニュアルではなく、誰かが更新し続けている5ページです。Nerdtechnic（恩梯科技）はHelper CTOとしてあなたのシステムを引き継ぎ、最初の1か月でこの5つを書き上げ、その後は変更のたびに更新していきます。最初のステップは60分のシステム健診です。コードさえ見せていただければよく、本番環境のアカウントやパスワードは不要で、3～5営業日で読んで分かる1枚のレポートをお渡しします。あなたのシステムが今もまだ「全部コードの中」という状態なら、まずその最初の1ページを一緒に書き出しましょう：Helper CTO：システム保守プラン。