技術共有
Helper CTO シリーズ 29|システム健診レポートを受け取ったあと:3つの結論それぞれの次の一歩
1ページの健診レポートの最後の一行は、そのまま引き継げる・先に整理してから引き継ぐ・作り直したほうが安く済む、の3つの結論のいずれかである。本記事は各結論の先にある道、費用の考え方、そしてレポートを受け取ったあとにできる3つのこと——何もしないことを含む——を解説する。
「ドキュメント?辞めるときに『全部コードに書いてある』と言われました」。この言葉のツケは、次のエンジニアが入社した最初の週に具体的な形で現れます。彼はこのシステムがどう動いているのかを推測するのに3日を費やし、その3日間にシステムに何か起きても、対処できる人が誰もいません。あなたはドキュメントを軽視しているわけではなく、最低限何が必要かを誰も教えてくれなかっただけです。以下の5つを、それぞれ1ページ以内でまとめます。
発掘調査とは、新しく来た人が何日もかけてこのシステムがどう動くのか推測し、推測しながら試し、その失敗のツケをあなたが払うということです。彼が推測しなければならないのは次のことです。
さらに厄介なのは、推測できないものがあることです。旧担当エンジニアのパソコンに残っていたデプロイコマンドや、本人しか知らないログイン方法は、書き残されていなければ消えてしまいます。
分厚い技術仕様書は必要ありません。そういうものは誰も更新しません。必要なのは、このシステムを見たことのないエンジニアが1日で対応できるようになる5枚の紙です。
| ドキュメント | 何を書くか | ないときのツケ |
|---|---|---|
| システムがどこで動いているか | ホスティングプラットフォーム、アカウント、ドメイン、使用している外部サービス | 一件ずつ電話で問い合わせ、分からなければ新しく作る |
| どうデプロイするか | どこからコードを取得するか、何を実行するか、成功をどう確認するか、どう戻すか | 誰も本番に反映する勇気が出ない、または反映しても戻せない |
| データがどこにあるか | データベースの場所、ファイルの保存先、バックアップの頻度と保存場所 | 問題が起きて初めてバックアップが動いていなかったと気づく |
| 誰がログインできるか | どんなアカウントがあり、それぞれの権限、パスワードの入手先 | 辞めた人がまだ入れて、入るべき人が入れない |
| よくある問題への対処法 | 過去半年に起きたことと、そのときの解決方法 | 同じ問題を毎回一から調べ直す |
5つ合わせても5ページを超えません。これは「明日から来るエンジニア」のために書くものであって、自分用のメモではないことを忘れないでください。
5つを一度に書き切れない場合は、まずこの2つを書きましょう。残りの3つはゆっくり補えばいいです。
「ものを取り戻す」ことと「ものを書き残す」ことは、一緒にやるべき2つの作業です。エンジニア退職後にまず取り戻すべき12のものの記事が扱うのは前者です。私たちがシステムを引き継ぐ最初の1か月(引き継ぎ後の最初の1か月に私たちがすることを参照)では、1週目に作成する「現状マップ」がこの5つの初版になります。
ドキュメントの最大の敵は「書かれていないこと」ではなく、「書かれたのに誰も更新せず、半年後には現状と合わなくなり、かえって次の人を誤らせること」です。3つの方法があります。
ドキュメントが生きているかどうかを判断するのは簡単です。「担当者が1週間休んだら、誰かがこの5ページを見てシステムを維持できるか」と自問してください。答えが「いいえ」なら、更新すべき時です。
多くのベンダーはドキュメントを残しません。その理由を正直に言えば、ドキュメントが少ないほど顧客が離れられなくなるからです。私たちのやり方はその逆で、理由もきわめて実際的です。
引き継ぎで気をつけるべきその他の詳細は、システム運用引き継ぎガイドの記事に完全なチェックリストがあります。
ドキュメントの価値は、どれだけきれいに書かれているかではなく、いつでも担当者を交代できるかどうかにあります。
引き継ぎをブラックボックスにしないために必要なのは、分厚いマニュアルではなく、誰かが更新し続けている5ページです。Nerdtechnic(恩梯科技)はHelper CTOとしてあなたのシステムを引き継ぎ、最初の1か月でこの5つを書き上げ、その後は変更のたびに更新していきます。最初のステップは60分のシステム健診です。コードさえ見せていただければよく、本番環境のアカウントやパスワードは不要で、3~5営業日で読んで分かる1枚のレポートをお渡しします。あなたのシステムが今もまだ「全部コードの中」という状態なら、まずその最初の1ページを一緒に書き出しましょう:Helper CTO:システム保守プラン。
深く取り組む価値のある、少数の企業と長期的な関係を築きます。
お困りですか?
LINEで直接ご相談ください