未知の技術導入におけるドキュメント作成のすすめ
多くのエンジニアやプロダクトマネージャーが、ドキュメントを書く必要があると感じつつも、なかなか取りかかれないことが多いのではないでしょうか？
今回は、私がどのようにドキュメントを作成しているか、そのサンプルを紹介しつつ、未知の技術を導入する際のポイントについても触れていきます。
ドキュメントを書く目的
ドキュメントを書く目的はいくつか考えられます。例えば：
認識齟齬を減らす：チームメンバー間での共通理解を確立するため。
将来の誰かに向けて残す：後からプロジェクトに参加する人が理解しやすいように。
思考の整理：自分自身の考えを明確にするため。
ここで重要なのは、複数の目的を同時に追求しないことです。今回は、特に「思考の整理」を最大の目標として利用するユースケースを紹介します。
思考の整理のためのドキュメント作成
未知の技術を導入する際には、How が不明確であるため、調査した内容を迅速に整理することが重要です。
調査を進めているうちにゴールを見失ったり、ゴールに沿っていないことを調査してしまうこともあります。これを避けるために、ドキュメントを作成することが必要です。以下のステップを踏んでドキュメントを作成します。
ステップ 1：現状
現状を把握するためには、技術資産とヒューマンリソースの現状を明確にすることが重要です。
技術資産の現状：現在使用している技術スタック、システムのアーキテクチャ、既存のインフラなど。
ヒューマンリソースの現状：チームメンバーのスキルセット、経験、リソースの配置状況など。
ステップ 2：問題点
現状に対してどのような問題が存在するかを明確にします。問題点を具体的に書き出し、その影響を理解することが重要です。
ステップ 3：目標
問題を解決するための具体的かつできれば測定可能な目標を設定します。
ステップ 4：調査項目の洗い出しとフィードバックの記録
調査項目の洗い出しと調査結果のフィードバックは相互に行き来するプロセスです。
まず、ゴールを達成するために必要な要素で、技術的に後戻りしにくい分野・大きなテーマに調査項目を絞り込みます。
そのためには頭の中にインデックスを作ることが重要です。
関連のテーマや用語を YouTube や Google 検索で調べ、いくつかの動画やドキュメントを発見し、概要を掴むことを意識します。
ここで頭をあれこれと悩ませてもあまり意味がないので、頭の中にインデックスを作るだけです。
概要をざっくりと把握した段階で早めに調査項目を作成します。
その後できるだけ早いタイミングで情報を共有します。
そしてそれを関係者（他のエンジニアやドメインエキスパート、ビジネスの人など）と一緒に確認します。
これにより、思い違いや見落としがないかを確かめてブラッシュアップします。
調査を進める中で新たな情報や課題が見つかった場合、それをすぐにフィードバックとして記録し、必要に応じて調査項目を更新します。
調査の進め方
調査期間はできるだけタイトな時間で設定し、後戻りが難しそうなテーマからどんどん調査を進めます。未調査の項目が残っても、時間が来たら共有することが重要です。未調査項目は未調査項目としてそのまま伝え、実現が不可能だった場合の代替手段についても検討し、必要であれば関係者と合意を取ります。
ステップ 5：解決策の検討と合意
調査結果を基に、関係者と設計のトレードオフや実装手段（HOW）について話し合います。具体的な実装手段を決定し、合意を得た上で実装を進めていきます。この過程で、関係者とのコミュニケーションを密に行い、問題点や疑問点を解消しながら進めることが重要です。
弊社のマルチテナント実装例
では、上記のステップを踏まえて、現在未リリースのプロダクトにて先日マルチテナントの実装をしたので、それを例として私の経験談を話します。
ステップ 1：現状
技術資産の現状：現在、弊社のシステムにはマルチテナント機能が実装されておらず、企業ごとのデータ隔離が十分に行われていません。
ヒューマンリソースの現状：過去に私はマルチテナントの実装を経験したことがなく、具体的な実装手段や設計パターンについての知識も不足していました。
ステップ 2：問題点
企業ごとのデータ隔離が不十分なため、企業に提供するサービスのセキュリティとデータ管理に問題が生じる可能性がある。
ステップ 3：目標
企業ごとのデータ隔離を実現し、マルチテナント機能を導入することで、セキュリティとデータ管理を強化する。
具体的な目標は以下の通りでした。
企業 A は企業 A 以外のデータを見られないようにする（テストコードで確認可能）。
弊社の管理アカウントを使えば、企業 A も企業 B もデータの閲覧ができること。
ステップ 4：調査項目の洗い出しとフィードバックの記録
マルチテナントアーキテクチャの基本概念
データベースの分離方法（物理分離、論理分離）
テナントごとのアクセス制御
セキュリティ対策
スケーラビリティとパフォーマンス
実際の導入事例とベストプラクティス
今回はテーマの大きさにしてはややタイトすぎるかなと思いつつ調査期間を2日に定めました。
締切効果を狙ってややタイトすぎる時間を設定しました。
後戻りが難しそうなテーマからどんどん調査を進めていきました。
それぞれのテーマについて、Youtubeやドキュメントなどをサーチして読んでいきます。
都度ChatGPTとディスカッションしたりして調査項目に対する調査結果をドキュメントに記載していきます。
調査結果から更なる調査項目が発生することも多々あったので、それを都度ドキュメントに追記していきました。
ただし、小さな調査項目は追記するだけで、調査自体はせずできるだけ大きなテーマにフォーカスするようにしました。
今回は2日間だとタイトだったので、いくつかのテーマについては未調査項目として残りましたが、大きなテーマから調べていたので不確実性はかなり少なくなっていました。
その後、調査結果と未調査項目の内容をさくっとまとめました。
ステップ 5：設計と実装の進め方
調査結果を基に、弊社の代表に内容を共有し、設計のトレードオフや実装手段について話し合いました。
8割型、内容については合意を得られたので、あとは実装中に発生する課題に対して都度相談しながら進めていくようにしました。
実際、途中で課題がいくつか発生したのですが、その都度相談して解決策を見つけることができました。
結論
思考の整理を目的としたドキュメントの作成は、未知の問題に対処するための強力なツールです。特に正しい現状理解と正しいゴール設定が重要です。
具体的な手順を踏むことで、問題を明確にし、効果的な解決策を見つけることができます。これにより、プロジェクトの成功に向けた一歩を踏み出すことができるでしょう。
未知の技術を導入する際には、調査を丁寧に進める一方で、検討に時間をかけすぎないように注意し、素早く実装し、フィードバックを得るプロセスを繰り返すことが重要です。
実装時間に余裕があれば、課題が発生したとしても、ある程度方針転換をする時間を取ることができるからです。