はじめに
デリッシュキッチンでiOSアプリ開発を担当している池田です。
皆さんは開発現場でこんな経験はありませんか。「あの機能の仕様が知りたいのに、どのドキュメントを見ればいいのかわからない」「ドキュメントはあるけれど、欲しい情報が見つからない」。 多くの組織でドキュメントを残す取り組みは行われていますが、ドキュメントは「残す」だけでは価値を発揮しません。この記事では、ドキュメントを活用するための考え方をご紹介します。
よくある問題事例
Case 1
ある機能の不具合が見つかり修正が必要になった。実装を見ても該当箇所がどのような経緯でそうなっているかがわからない。正式なドキュメントが見つからず、チャットの履歴を遡って仕様決定に関わった人を探し出し、口頭で詳細を聞くことになった。
Case 2
新機能開発時にPdMが施策企画書を作成し、エンジニアがそれを元に実装を進める。しかし施策終了後、「現在の仕様はどうなっているのか」を知りたくなった際、施策当時のドキュメントから現状を読み取ることが困難だった。複数の施策が重なり、どれが最新の正しい状態なのかがわからない。
「ドキュメントが残っていないからわからない」ということは様々な組織で聞くことですが、実はどこかを探せばそのような情報は残っていることが多々あります。問題なのは利用しやすい状態で残っていないことなのです。
ドキュメントマネジメントの基本原則
ドキュメントは見る目的も対象とする読み手も異なります。この違いを意識することでドキュメントはより価値のある情報にすることができます。
ドキュメントの分類
ドキュメントは大きく2種類に分けることができます。一つは更新型ドキュメント、もう一つは記録型ドキュメントです。
例えばアプリの画面に配置されている特定の要素をタップしたときに、どのようなことが起こるのか、といったことは更新型である画面仕様書に記載されます。施策が実施され動作が変更になった場合はドキュメントを更新します。これを読むことで常に正しい動作を知ることができます。 一方で施策を実施するときのドキュメントは記録型ドキュメントであり、施策を実施する目的や実施した結果などが記載されます。これを読むことで過去の施策を実施した当時の状況を知ることができます。
このように2種類のドキュメントが伝えるものは大きく異なります。アプリケーションの動作を表したいのであれば、記録型である施策企画書を積み重ねるのではなく画面仕様書や機能仕様書といった更新型ドキュメントで現在の正しい動作を記載し、更新し続けることが重要です。
以上のことをまとめると次のようになります。
更新型ドキュメント
- 目的: 現在の正しい情報を提供する
- 更新方針: 変更があるたびに内容を更新
- 例: 機能仕様書、画面仕様書、API仕様書、作業手順書
記録型ドキュメント
- 目的: その時点での情報や判断を記録する
- 更新方針: 原則として後から変更しない
- 例: 議事録、施策企画書、ADR（技術的意思決定の記録）、日報
ドキュメントではひとつのことにフォーカスする
ひとつのドキュメントには情報を詰め込みすぎないようにしましょう。
もしひとつのドキュメントに複数の目的を持たせてしまうと、そのドキュメントをどのように扱うのか、更新すべきかどうか、どのようなときに見たら良いのかといったことがわからなくなってしまいます。
そのような混乱を招かないためにもひとつのドキュメントにはひとつの関心事のみを記載するようにしましょう。
実践的な運用方法
ドキュメントの命名を工夫する
ドキュメントはタイトルを見て一目でどのようなドキュメントなのかを判別できることが重要です。
命名規則の例
- 議事録: 20240115_UX向上定例
- 機能仕様書: 【仕様】ユーザー登録機能
- ADR: ADR-001_データベースエンジン選定
- 施策ドキュメント: 【施策】20240202_ログイン率改善
- 調査ログ: 📝特定の端末で動画の再生が不安定になる
アイコンやプレフィックスを統一することで、ドキュメント一覧での視認性が向上します。チーム内で命名ルールを決めておくことで、必要な情報により早くたどり着けるようになります。
命名を考えるためにはどのような目的のドキュメントなのかをはっきりさせる必要があります。命名を意識することは結果としてドキュメントの目的を意識することにも繋がります。
開発サイクルとドキュメント
前章で触れたように、ドキュメントには固有の役割があります。これらは施策を回す際にどのフェーズにはどのようなドキュメントが必要なのかということに結びつきます。
ひとつの例を見てみましょう。
施策を実施するときにいきなり機能仕様書や画面仕様書を作ることはないでしょう。最初に作るのは施策企画書です。この施策企画書は新規に作ることもありますが、既存の改善策の場合はすでにある機能仕様書などを元に作成します。元の状態をどのようにしたいのかがミーティングで検討され、施策の実施を決定し、その施策の詳細がドキュメントに落とし込まれます。
次に施策企画書を元に機能仕様書や画面仕様書を作成、及び更新します。ここで記録型ドキュメントの情報が更新型ドキュメントに落とし込まれることになります。これらのドキュメントを元にエンジニアが実装を行います。
機能がリリースされた後に実施した結果を分析し、その分析結果を追記することで施策企画書は完成します。そしてまた新しい施策が実施されるサイクルが回ります。
まとめ
ドキュメントを「残す」から「活用する」へ変えていくには、以下の3つの原則を意識することから始まります。
- 目的に応じた使い分け: 更新型（常に最新）と記録型（時点記録）の性質を理解する
- 単一責任の原則: 一つのドキュメントには一つの関心事のみを記載する
- 見つけやすさの確保: 命名規則とライフサイクル管理で必要な情報にたどり着きやすくする
これらを実践することで、「ドキュメントはあるけれど活用できない」という問題を解決し、チーム全体の生産性向上につながります。まずは現在のドキュメントを更新型・記録型で分類することから始めてみてください。
