こんにちは。カケハシで開発ディレクターの笹尾です。
前編の方針を踏まえ、ここからは具体の記載方針と運用に踏み込みます。
はじめに
ドキュメント設計はアーキテクチャ設計と同義です。求められるのは、スケールと複雑性に耐える持続可能な設計です。
最初から完璧は狙いません。想定できない課題も多いため、『作る→使う→直す』のループで育てながら、変化を受け入れやすい設計を目指します。
本記事を通して、ドキュメント成長過程の楽しさに触れ、チームがドキュメントに触れ合う機会を作る参考になれば幸いです。
実際の記載方針を設計する
前編で定めた大まかなドキュメント設計の方針を、「どこに／どのフォーマットで／どんな構成で」へ落とし込みます。
ここからは実際の『Musubi AI在庫管理開発チーム』での取り組みを例に、ドキュメント設計の具体的な記載方法や運用について説明します。
目的から分解したドキュメントライフサイクルに対する要求
AI在庫管理ではPDFとWebの2系統出力、巨大なユーザーマニュアルの編集コスト削減、エンジニアが書きやすい軽量記法、自動化、アーキテクチャを映す文書構造の維持を要求にまとめました。
またエンジニアだけでなく、ユーザーマニュアルを記載するCSメンバーもドキュメント記載の主体になるためツールを含めた記載容易性も重要な要求です。
- PDFとWebの両立
- 生成・公開の自動化、PDF最適化、共通スタイル、スタイル／コンテンツ分離
- 記載容易性
- Markdown相当の軽量マークアップ（移行コスト低／画像・表・ダイアグラムのテキスト記述／再利用可能な参照構造）
- レビューとフィードバック
- レビューシステム連携、差分確認、ルール統一
- 文書構造の維持
- アウトライン／ファイル構造／クロスリファレンスの保持
記載フォーマットとドキュメント管理
上記の要求から、『AsciiDoc（Asciidoctor） + Antora + GitHub』 を採用しました。
AsciiDocは軽量マークアップ言語の一種ですが、表・参照・分割構成に強く、PDFとWebの両立が容易。GitHubでのプレビューやレビューと相性が良く、Antoraでバージョン別に体系化できる技術ドキュメントの記載に適したフォーマットです。
なお、ユーザーマニュアルを記載するCSメンバーが本当に利用できるかは、試験的に記載してもらいフィードバックを得ながら確認した上で採用を決定し、実際の運用の中で継続的に改善しています。
-
フォーマット：AsciiDoc
- 軽量マークアップ（Markdown→AsciiDocは Kramdown AsciiDoc で移行可能）
- スタイルとコンテンツ分離
- Git親和性／ダイアグラム連携／参照構造
- PDF&Web両立出力：HTML（Asciidoctor + Antora）／PDF（Asciidoctor PDF）
-
管理：GitHub
- バージョン管理、Pull Requestレビュー、バージョン差分の可視化
-
CI/CD（GitHub Actions）
- 出力・検証・デプロイの自動化
- TextLintで記載ルールを支援
この構成により、「書きやすさ×構造化×自動化」の三点セットで、更新し続けられるドキュメント基盤を目指しました。
情報の構造と構成
仕様書の記載を始めるには、記載すべき情報を洗い出し、構造化する必要があります。
本チームでは、結合度が高く既存プロダクトに対して、現実的な選択として「利用方法と機能分類を軸」に構造化しました。
また、構造化の判断は以下の観点で行っています。
プロダクト開発初期
プロダクトやサービス全体のドメインをサブドメイン単位で分割し必要な情報を洗い出すことをお勧めします。
ドキュメント記載時点でサブドメイン分離を行うことで、アーキテクチャーも結合度やシステムの複雑度を下げやすくなり、将来の拡張性も高まります。この段階では、情報の粒度はあまり細かくせず、大まかなカテゴリ分けを行うことが重要です。
プロダクトがある程度成熟している場合
既存のプロダクトアーキテクチャを分析した上で、現実的に実現可能な理想状態のアーキテクチャ構造を描いた上でドキュメント構造を最適化することをお勧めします。
現実的な理想状態を先にドキュメントに落とし込むことで、システムの設計を変えるより低いリスクで将来的な改善の指針と照らし合わせて開発を進めることができます。
運用の流れ
ドキュメントを陳腐化させないために最も重要なのはドキュメントの更新を促進する運用の流れの設計です。
お客様に直接届くマニュアルはCSメンバーが継続的に更新する必要があるため、他のドキュメントの更新を促進する「流れ」を作りやすくなります。
ですから僕たちは「ユーザーマニュアル→外部仕様書」の順で整備しました。
その上で、外部仕様を「同じ場所で閲覧」できることで相互参照を容易にし、CSメンバーが更新時に仕様の不明点を参照しやすい設計にしました。
さらに「リリース時は外部仕様書の更新を義務化」し、システムテスト項目に「外部仕様の網羅性テスト」を組み込むことで、記載の漏れを減らしています。
流れを止めない工夫
運用の流れを設計する際に注意すべき点もあります。
それは常に完全な記載は難しいため、完璧を求めると流れが滞ってしまうことです。
ドキュメントの更新を促進する情報の流れを設計し、ドキュメントの更新が自然に行われる中で『気づいたら直す、改修時は必ず見る、記載漏れは追記する』など、継続的に改善する仕組みも重要です。
また、AI在庫管理ではサポートデスクのメンバーも外部仕様書の内容を閲覧してお客様への案内に利用した上で、それでも発生する不明点の確認や調査の依頼などの機会も利用して、ドキュメントの記載と改善も行うような流れを意識しています。
多くの人が触れる導線にドキュメントを置くことで、ドキュメントの価値を高め、更新の流れを止めない工夫があることで、一時に完璧を求めずともドキュメントの品質を高め続けることが可能になります。
一朝一夕では成らない
ここまで説明した設計を一朝一夕で成し遂げることは困難です。
大まかな設計方針を決めたら、『設計→運用→改善』のループを小さく速く回します。
「当たり前品質」に届くまで時間がかかるため、狭い範囲から始めるのが現実的です。
試行錯誤の中で目的も変化するため、定期的に見直すことも重要です。
また目的に対してアプローチが合っているかの検証も重要になるため、特に初期の構築時は設計サイクルを短く回数を重ねて回すこと意識すると良いと思います。
AI在庫管理開発チームのキュメントの歩みと課題
AI在庫管理のドキュメントは最初にユーザーマニュアルの記載から始めた上で、ユーザーマニュアルを元にしながら外部仕様書の記載を進めました。
ユーザーマニュアルは一つのPDFとして出力する必要があったため、外部仕様書の記載時も1つのドキュメントを1つのHTMLとして出力する構成になりました。
しかし外部仕様書の記載量が増える中で結合度の低い構成で記載できる工夫が必要になり、Antoraを導入するなど、ドキュメント設計の改善を繰り返しながら成長させた歩みがあります。
このような歩みの中で、僕たちの外部仕様書には以下の課題が残っています。
- 外部仕様に手順が残り、仕様として冗長
- 文章中心で、表・論理式の表現が少ない
上記の課題はドキュメントのボリュームが増えた今、全て改善するのは困難と捉えがちかもしれません。
しかしプログラミングのリファクタリングと同様に、手の空いたタイミングで共通的な部分を少しずつ修正したり、機能改修時の記載修正のタイミングに修正するなど徐々に改善を進めていくことで解決可能だと考えています。
品質向上ハンドブックの公開（同じ仕組みに乗せて製本まで）
先日公開した『Musubi AI在庫管理開発チームの品質向上ハンドブック』内で定義されているプロセスとフローは、ドキュメント運用によって強化される仕組みを持っています。
その一方でFindy Team+ Award 2025 の受賞決定から授賞式までの短期間で印刷された状態で用意できたのは、ここまでに説明したドキュメント設計の仕組みに乗せたからこそ実現できています。
品質向上ハンドブックの内容は当初 「Markdown + 社内esa管理」となっており、記載統一や外部ツール連携が難しい状態でした。
そこで 『AsciiDoc へ変換 → GitHub 管理 → Antora 公開 → PDF 自動化』に乗せ替えることで、小さな追加工数で製本レベルの PDF を用意できました。
入稿データの作成は完全自動ではなく、塗り足しの必要がある表紙や一部の図に対して手作業が必要でしたが、最小工数で製本までの道筋を確立でき機会があれば更新版も印刷しやすい仕組みを手に入れました。
プロダクトライフサイクルに継承の仕組みを取り入れよう
プロダクトやサービスは進化しながら関係者も前提も変わり続けます。
その変化に応じた知識の継承を意識的に行う仕組みを事前に準備することが重要です。
日本には「式年遷宮」という一定の周期で神社の建物を建て替える伝統的な建築物の再建と継承の仕組みがあります。
式年遷宮は、建物の更新を定期的に多くの人が関わって実際に実行することで世代間の垣根を超えて技術・知識を更新しながら伝える仕組みです。
プロダクトやサービスに関わるのであれば、変化の後で継承に悩むのではなく、変化の過程で継承可能な設計として、常に最新の正しい情報にアクセスできることで知識を伝承する枠組みを持ち続ける必要があります。
その枠組みの重要な一部としてドキュメントという「流路」を設計しておくことが肝心です。
まとめ
ドキュメント設計は単なる情報整理のための設計ではなく、正しい情報が流れ続ける仕組みの設計です。
ドキュメントの質を継続的に向上するにはアーキテクチャ同等の設計力が必要になるため、設計力を高めるためにも非常に有益です。
またドキュメント記載の過程では矛盾や複雑性が早期に見つかり、品質向上にも寄与します。
私自身、ドキュメント記載は得意ではありませんが、1つのドキュメントの価値を最大化する設計でモチベーションを上げ、実務に効く成果を考える中でモチベーションの維持につなげてきました。
ぜひ、皆さんの現場でも「目的志向で利用用途を広げる設計」から始め、小さく回して継続的に強くする運用を進めてみてください。
