こんにちは。カケハシで開発ディレクターをしている笹尾です。
『Musubi AI在庫管理開発チーム』での取り組みを例に、ドキュメント設計の重要性と実装の流れを紹介します。
内容が多岐に渡るため、前編・後編の2回に分けて解説します。
はじめに
最初に強調したいのは『ドキュメント設計はアーキテクチャ設計そのもの』だということです。
逆に言えば、ドキュメント設計が弱いチームは設計力も伸びにくいとも言えます。ところが実務では、ドキュメント設計に触れる機会が少なく、結果として「後回し」になりがちです。
本記事が、チームの設計力を底上げするヒントになれば幸いです。
目的志向で利用用途をとらえて広げる
ドキュメント設計のつまずきは、「書くこと自体が目的化」してしまうことです。
設計の出発点を「どこに／どんなフォーマットで／どんな構成で」としてしまうと、利用用途が狭いまま固定されがちです。
まず考えるべきは、誰が・どんな目的で・どう使うと価値が最大化されるか。受け手は多様で、開発チームに限定されないほど記載のモチベーションが揺れにくくなり継続的に価値を向上しやすくなります。
また、受け手と目的が明確になることで、情報の種類や構造、区分も見えやすくなり、スコープを絞った設計が可能になります。
「形式」は後から変えられます。「価値の最大化」を先に設計することをおすすめします。
AI在庫管理開発チームのとりくみ
本プロダクトでは、エンドユーザーから開発メンバーまで幅広い受け手と用途を想定して設計しました。
特に、CS（カスタマーサクセス）やサポートデスクのメンバーも主要な閲覧者に含めることで、不明点の問い合わせを減らし、開発チームの負担軽減を図りながらドキュメントの価値を高めることを目指しました。
それにより社内外の情報共有が効率化され、サポート時の顧客体験も改善。さらに継続的な記載・更新の流れが活性化することを狙いました。
閲覧対象ユーザーと目的
お客様（導入担当者／エンドユーザー）向け
- 最新情報の提供
- 操作方法の理解
社内（共通）向け
- 仕様問合せ・調査の削減
- 単一情報源での認識統一
- 新メンバーのオンボーディング効率化
- 離脱時のナレッジ継承
- 管理主体の異なるドキュメントを一箇所で閲覧可能
開発チーム（PdM／デザイナー／エンジニア）向け
- 影響範囲（仕様／運用）の特定、論理整合性の確認
- 意思決定の記録、期待動作／仕様バグ／実装バグの判別
- テストケース作成の効率化
CS／サポートデスク向け
- お客様対応の迅速化
- 正確な情報の取得
情報の種類を分類し、必要最低限を押さえる
情報の分類は、正確性・一貫性・運用コストを左右します。
分類すると外部制約が見えたり優先順位がわかりやすくなり「どこに／どんなフォーマットで／どんな構成で」の設計が進めやすくなります。
フロー情報とストック情報
情報を取り扱う上で、維持管理や構造化のレベルを決めるために「フロー情報」と「ストック情報」に分けることが有効です。
この中で、ストック情報に重点を置くことで、ドキュメントの価値を最大化しやすくなります。
- フロー情報：時間の経過とともに参照が減る情報（例：チャット、議事録、開発状況）
- ストック情報：恒常的に参照される情報（例：ユーザーマニュアル、設計書、APIドキュメント）
判断に迷いやすい例として PRD（Product Requirements Document）が挙げられます。
この時、プロダクト開発のサイクルにおいて過去に記載したPRDについて、常時参照したりアップデートするならストック情報とし、要件ごとに新規化され過去参照が少ないならフロー情報として扱うなど、割り切った運用をすることが重要です。
この割り切りは、ドキュメント設計の初期段階ではスコープを絞る方向を試しながら、徐々に改善していくことをお勧めします。
AI在庫管理開発チームのとりくみ
ストック情報の選定は「閲覧者が広い／参照頻度が高い」を基準にしました。
- フロー情報：PRD、ADR（Architecture Decision Record）、議事録
- ストック情報：ユーザーマニュアル、外部仕様書、全体構成図、API仕様書、DB仕様書
その上で、ストック情報の中でも特に重要な「ユーザーマニュアル」から整備し、「外部仕様書」と順次整備していきました。
現在状態とスナップショット、経過情報
情報の時系列をどう扱うかも分類が必要です。
例えば、現在状態、スナップショット、経過情報の3つに分けることも有効です。
- 現在状態: 本番環境の最新仕様
- スナップショット: 過去の改修時点の情報
- 経過情報: 変更履歴や議論の履歴
この分類は利用シーンが異なるため、誰が・いつ・何のために見るかを意識すると流れを設計しやすくなります。
設計の初期時点では目的を達成できる必要最低限に絞りつつ、それ以外の情報は必要に応じて参照できるようにすることが重要です。
AI在庫管理開発チームのとりくみ
本プロダクトでは閲覧するメンバーを増やすため、共有する情報は必要最低限に絞ることを意識しました。
これにより、現在状態は社内全員に公開でき、プロダクトのリリースとドキュメントの更新サイクルを同期しやすくなります。
また、スナップショットと経過情報については必要な時のみアクセスするように設計しています。
以下の内容はその後の設計の具体例も含んでいますが、その背景としてGoogle Docs等の機能に頼ると経過情報が同一のドキュメント内に混在しやすく、スナップショットの扱いも難しいなどの特徴があるため、何をどれぐらい望んで諦めるかの判断例として参考にしてください。
- 現在状態：本番環境の最新仕様。社内全員が閲覧可能
- カナリアリリース／A/Bテストなど複数バージョンが存在する場合はバージョン別に閲覧可能
- スナップショット：Gitで管理（必要時に参照）
- 経過情報：GitHubとJiraを紐づけて履歴管理
情報の公開区分や信頼区分
情報の種類を分類する際に、情報の公開区分や信頼区分を考慮することも重要です。
- 公開区分：社内全体／特定チーム／お客様向け公開 など
- 信頼区分：草稿／レビュー前／レビュー済 など
初期から全てを厳密に定義する必要はありませんが、初期から意識することでフォーマット設計や運用設計が適切になり後の改善がスムーズになります。
AI在庫管理開発チームのとりくみ
僕たちは以下の様に分類しました。
以下の内容はその後の設計の具体例も含んでいますが、その背景としてGoogle Docs等の機能だけでは達成できない部分があり、他の仕組みで補完する必要があるため、何をどれぐらい望んで諦めるかの判断例として参考にしてください。
- 公開区分: 原則社内全員が閲覧可能
- ユーザーマニュアルは手動でお客様向けにサイトに公開
- 信頼区分:
- 草稿: 個人のローカル環境や個人のGitHubリポジトリで管理
- レビュー前: GitHubのPullRequestでレビュー待ちの状態
- レビュー済: PullRequestマージ後に自動で社内公開
まとめ
本稿では『目的志向で受け手を広げる』ところからスタートし、『情報を分類してスコープを決定』する考え方を紹介しました。
利用用途を広げることでドキュメントの価値を最大化し、スコープを絞ることで実装と運用の負荷を抑えながら、価値密度も高められます。
この記事を読んだ皆さんがドキュメント設計の重要性を理解し、実務に活かす一助となれば幸いです。
後編では、実運用に向けたフォーマット選定、構成設計、運用を具体的に解説します。
