コンテンツにスキップ

ドキュメント運用ガイド

このページは、docs/ を更新する人向けのクイックガイドです。閲覧者向けの総合ポータルは docs/index.md を使い、このページでは「どこに書くか」「何を一緒に直すか」を整理します。特に、共有導線として使う 05. 納品・運用ポータル と、全体ポータルである docs/index.md の役割を混ぜないことを重視します。

まず確認するもの

目的 参照先 補足
ドキュメント全体の入口を確認する index.md 読み手向けの総合ポータル
納品・共有導線を確認する 05-delivery/index.md 検収・運用・引き継ぎの共有入口
docs 配下の更新ルールを確認する AGENTS.md 受け入れ側視点と用語ルール
配置・検証ルールを確認する documentation-rules.md どこへ書くか、どう検証するか
要件の根拠を確認する specifications/index.md PDF / Excel / DOCX などの一次情報
用語を確認する glossary.md SMILE 用語やプロジェクト固有語の統一

共有ポータル更新時の判断

  • docs/index.md は全体ポータルとして、広い資料群の関係を説明しつつ、優先読者を docs/05-delivery/index.md へ案内する。
  • docs/05-delivery/index.md は共有導線の本体として、検収担当 / システム管理者・運用担当 / 引き継ぎ開発者・保守担当が読む順番を示す。
  • docs/index.md に詳細な手順や契約条件を重複記載せず、役割と目的に応じた入口・関係整理に徹する。
  • Cloudflare Pages は顧客共有用の絞った導線、.mkdocs/spec.yml から出力する PDF は公式納品物、という前提を崩さない。
  • Cloudflare Pages に載せるのは検収・管理運用に必要な導線を基本とし、引き継ぎ資料は docs/05-delivery/ と公式納品物 PDF 側で確認する前提で整理する。

どこに書くか

場所 書く内容
docs/01-requirements/ 整理済み要件、補足要件、受入観点
docs/02-design/ 設計判断、アーキテクチャ、データモデル、画面設計
docs/03-implementation/ 実装詳細、運用手順、開発/インフラ手順
docs/04-project-management/ 進捗、課題、会議録、公開計画、要件変更管理
docs/05-delivery/ マニュアル、保守、引き継ぎ、納品資料
docs/06-optional-features/ 追加機能案、将来拡張候補
docs/07-frontend/ Frontend 固有の UI ルール、UI プレビュー運用
docs/client-documents/ 顧客や対外共有を前提とした資料
docs/migration/ データ移行、インポート、移送手順
docs/technical-analysis/ 技術検証、比較、事前調査
docs/technical-specifications/ 実装に近い確定補助仕様
docs/plans/ 共有前提の計画書（個人作業メモは置かない）
docs/archive/ 現行ではない旧版文書

命名と入口のルール

  • repo 管理対象として追加する docs/ 配下のファイル名・ディレクトリ名は、原則 ASCII の lowercase kebab-case を使う。
  • AGENTS.md / README.md / index.md は固定慣例名として維持してよい。
  • docs/specifications/ の原本や docs/client-documents/ の受領資料など、外部由来の名称もそのまま維持してよい。
  • 番号付き主要セクション（01-requirements/〜07-frontend/）は index.md を必須とする。
  • images/, migration/, plans/, technical-analysis/, technical-specifications/ は補助領域として扱い、直接の入口が必要になった時だけ index.md を追加する。
  • docs/ 直下へ詳細テーマを直接置かず、まず既存のトップレベルカテゴリへ収める。

更新フロー

  1. docs/AGENTS.md と、対象ディレクトリに AGENTS.md があれば先に確認する。
  2. specifications/ やユーザー指定の情報源から根拠を確認する。
  3. 対象文書だけでなく、必要な index.md、関連ポータル、導線文書まで一緒に更新する。
  4. ナビゲーションや公開サイトの見え方に影響する場合は、以下の設定も確認する。
  5. .mkdocs/dev.yml
  6. .mkdocs/spec.yml
  7. apps/docs-site/cloudflare.yml
  8. 更新後は pnpm exec markdownlint-cli2 "docs/**/*.md" "README.md" と just docs-build を実行する。仕様書側にも影響する場合は just docs-spec も実行する。

更新時の注意

  • 同じ内容を別ファイルへ重複させない。既存ファイルへ統合できるならそちらを優先する。
  • 会議録や週報などの過去記録は、現在の正に合わせて書き換えない。
  • Admin UI という表現は避け、文脈に応じて Vendure Dashboard または React Dashboard を使う。
  • 顧客向け資料と内部向け資料は分けて管理する。
  • 新規文書を追加したら、少なくとも対応する index.md から辿れる状態にする。
  • 優先読者（検収担当 / システム管理者・運用担当 / 引き継ぎ開発者・保守担当）の導線を変える場合は、docs/index.md と docs/05-delivery/index.md の両方を確認する。