App Documentation Generator

実行中のウェブアプリをブラウズしてすべての画面をスクリーンショットし、公開できるクオリティのドキュメントを生成します。単なるスクリーンショット集ではなく、ユーザーがアプリの使い方を学べる構造化されたガイドです。

ブラウザツール検出

ux-audit と同じ — Chrome MCP、Playwright MCP、または playwright-cli。

URL解決

ux-audit と同じ — localhost より本番環境/ライブURL を優先します。

深度レベル

深度	スクリーンショット数	生成物	所要時間
quick	~10	シングルページのクイックスタートガイド。主要画面、ハッピーパスのみ。	10-15 分
standard	~30	完全なユーザーガイド。全ページ、主要ワークフロー、リファレンステーブル。	30-60 分
thorough	~80+	包括的なガイド。すべての状態、モバイルビュー、すべての CRUD フロー、トラブルシューティング。	1-3 時間
exhaustive	~150+	公開可能なドキュメンテーションスイート。thorough のすべて、さらに：ファーストステップチュートリアル、機能別の詳細解説、管理者ガイド、キーボードショートカットリファレンス、FAQ、HTML版。	3-6 時間

デフォルト: standard

ワークフロー

1. アプリの詳細を取得

ユーザーに以下を確認します：

• アプリURL（必須 — または wrangler.jsonc / 実行中の開発サーバーから自動検出）
• アプリ名（ガイドのタイトル用）
• 認証 — Chrome MCP は現在のセッション使用、Playwright は認証情報が必要
• 深度 — quick、standard、thorough、exhaustive のいずれか
• 対象読者 — 誰がこれを読むのか？（エンドユーザー、管理者、新しいチームメンバー、クライアント）

2. すべてのルートを発見

アプリをナビゲートしてページの完全なインベントリを作成します：

• サイドバー/ナビゲーションメニューを読む
• トップレベルアイテムとサブアイテムをすべてクリックする
• サブページ、ページ内のタブ、ネストされたナビゲーションに注目する
• 設定、プロフィール、管理者領域、ヘルプページをチェックする
• 各ページの URL と目的を記録する
• インタラクティブ要素（フォーム、ボタン、フィルタ）があるページを注記する

ドキュメント作成の進捗を追跡するためのタスクリストを作成します。

3. 各ページをドキュメント化

インベントリ内の各ページについて：

a. ナビゲートと準備

• ページにナビゲートする
• データが読み込まれるまで待機（スクリーンショットにスケルトン/スピナーなし）
• ブラウザを 1280x720 にリサイズして一貫性のあるスクリーンショットを取得
• ページに現実的なデータがあることを確認 — 「Test Client」や空のテーブルではなく

b. デフォルト状態をスクリーンショット

• データが入力された状態のクリーンなスクリーンショットを撮影
• docs/screenshots/ に説明的な名前で保存

c. ページセクションを記述

各ページについて以下を記述：

## [ページ名]

[1文で説明：このページは何のためで、いつ使用するのか]

![ページ名](screenshots/NN-page-name.png)

### 表示される内容
[主要要素を説明：サイドバーは X を表示、メイン領域は Y を表示、ツールバーは Z を持つ]

### できること
[利用可能なアクション、それぞれを簡潔に説明]

### 方法：[主要アクション]
1. [スクリーンショット参照付きステップ]
2. [ステップ]
3. [ステップ — 結果をスクリーンショット]

> **Tip:** [有用なショートカットまたは非自明な機能]

d. 主要ワークフローをドキュメント化

インタラクティブなページについては、各重要なステップでスクリーンショットとともに段階を追ってドキュメント化します：

### 方法：新しいクライアントを追加

1. 右上の **「クライアントを追加」** ボタンをクリック
   ![追加ボタンの位置](screenshots/12-clients-add-button.png)

2. 必須フィールドを入力 — 名前とメールは必須、その他はオプション
   ![新しいクライアントフォーム](screenshots/13-clients-new-form.png)

3. **「保存」** をクリック — 新しいクライアントの詳細ページに移動します
   ![クライアント保存確認](screenshots/14-clients-saved.png)

> **Tip:** どこからでも **Cmd+N** を押して新しいクライアントを作成できます。

e. 深度別の追加項目

追加項目	quick	standard	thorough	exhaustive
空の状態	スキップ	注記	スクリーンショット + ドキュメント化	スクリーンショット + 改善提案
エラー状態	スキップ	注記	トリガー + スクリーンショット	すべての検証エラーを記録
ダークモード	スキップ	スキップ	主要ページをスクリーンショット	すべてのページをスクリーンショット
モバイル (375px)	スキップ	スキップ	主要ページをスクリーンショット	すべてのページをスクリーンショット
すべての CRUD	スキップ	主要なもののみ	すべての操作	すべての操作 + エッジケース
設定/設定	スキップ	オプションを一覧	それぞれドキュメント化	例付きで各項目をドキュメント化
キーボードショートカット	スキップ	表示されている場合は一覧	完全なリファレンステーブル	専用セクション
検索/フィルタ	スキップ	説明	各フィルタをドキュメント化	あらゆる組み合わせをドキュメント化
権限/ロール	スキップ	スキップ	違いに注記	ロールごとに別セクション
API/統合	スキップ	スキップ	存在する場合は記述	エンドポイント + 例をドキュメント化

4. サポートセクションを記述

ページごとのドキュメント以外：

ファーストステップ（全深度）:

## ファーストステップ

### [アプリ名] へのアクセス
- URL: [本番環境URL]
- 対応ブラウザ: Chrome、Firefox、Safari、Edge
- モバイル: [レスポンシブ / PWA / 非対応]

### ログイン
[ログインページのスクリーンショット + ステップ]

### 最初の 5 分間
1. [ログイン後に最初にすること]
2. [2番目のこと — クイックウィン]
3. [3番目のこと — メイン機能を探索]

ナビゲーションガイド（standard+）:

## ナビゲーション

### サイドバー
[各セクションを説明する注釈付きスクリーンショット]

### クイックアクション
- **Cmd+K**: クイックスイッチャー — 任意のページまたはレコードにジャンプ
- **Cmd+N**: 新規 [項目] 作成
[その他のショートカット]

### パンくず / 戻るナビゲーション
[戻る方法、パンくずが表示される場所]

キーボードショートカットリファレンス（thorough+）:

## キーボードショートカット

| ショートカット | アクション |
|----------|--------|
| Cmd+K | クイックスイッチャー |
| Cmd+N | 新規 [項目] |
| Cmd+S | 保存 |
| Escape | ダイアログを閉じる / キャンセル |

トラブルシューティング（thorough+）:

## トラブルシューティング

### [エラーメッセージまたは症状]
**意味**: [説明]
**修正方法**: [ステップ]

### よくある質問
[ドキュメント作成プロセスから新規ユーザーを混乱させるもの — 仮説的な FAQ ではなく]

管理者ガイド（exhaustive）:

## 管理者ガイド

### ユーザー管理
[ユーザーの招待、ロール設定、アクセス削除方法]

### 設定リファレンス
| 設定 | 機能 | デフォルト | 推奨事項 |
[すべての設定がドキュメント化]

### データ管理
[エクスポート、インポート、バックアップ、アカウント削除]

5. 出力形式

Markdown（デフォルト）: docs/USER_GUIDE.md

• 相対画像パス: ![alt](screenshots/NN-description.png)
• GitHub-flavoured markdown — GitHub、VS Code、Obsidian でレンダリング

HTML（exhaustive 深度、またはリクエスト時）: docs/user-guide.html

• Tailwind CDN を使用した単一の自己完結型 HTML ファイル
• スクリーンショットを相対パスで（base64 ではなく — ファイルサイズを調整）
• 目次サイドバー、スムーズスクロール付き
• 印刷フレンドリーな CSS（@media print）
• ダークモード対応

スクリーンショット命名: docs/screenshots/NN-section-description.png

• ソート順序用の番号: 01-、02-、03-
• セクションプレフィックス: 01-dashboard-、05-clients-、12-settings-
• 説明的なサフィックス: -overview.png、-add-form.png、-saved-confirmation.png

6. モックアップと図

スクリーンショットを理解を助ける図と組み合わせます：

ワークフロー図（テキストベース、外部ツール不要）:

### クライアントがシステムを通じて移動する方法

新規問い合わせ → クライアント作成 → ポリシー追加 → 更新送信 → アーカイブ ↓ ↓ ↓ ↓ ↓ [メール] [クライアントページ] [ポリシーページ] [メールアウトボックス] [アーカイブ]

注釈付きスクリーンショット: スクリーンショットがコールアウトを必要とする場合、テキストで説明します：

![ダッシュボード](screenshots/01-dashboard.png)

ダッシュボードには以下が表示されます：
- **A**（左上）: クライアント数とアクティブポリシー
- **B**（中央）: 本日対応が必要な項目
- **C**（右）: 最近のアクティビティフィード

UI 要素リファレンス: 複雑なページについては、ラベル付き図が役立ちます：

### エディタレイアウト

| 領域 | 機能 |
|------|-------------|
| 左パネル | フォルダツリー — ノートを整理 |
| 中央パネル | ノートリスト — 選択したフォルダのノートを表示 |
| 右パネル | エディタ — ノートを記述およびプレビュー |
| トップバー | ナビゲーション、検索 (Cmd+K)、ビュー切り替え |

スクリーンショットの品質

• 解像度: 1280x720（デスクトップ）、375x812（モバイル）
• データ: 現実的なデータ。「Test」や「Lorem ipsum」ではなく。アプリが実際に使用される方法で使用します。
• タイミング: データが読み込まれるまで待機。最終ショットにスピナーやスケルトンスクリーンなし。
• 状態: ページが有用な状態 — データが入力、関連セクションが展開、主要機能が表示
• 一貫性: 全体で同じビューポートサイズ、ズームレベル、ブラウザ
• ダークモード: ダークモードをドキュメント化する場合、スクリーンショット撮影前に切り替え — 1セクション内でモードを混在させない

自律性ルール

• 単に実行: ページをナビゲート、スクリーンショットを撮影、ページコンテンツを読む、ドキュメントを記述
• 簡潔な確認: 大きなドキュメントファイルを記述する前に
• 先に尋ねる: 実データでフォームを送信する前、削除をクリックする前に
• Thorough/exhaustive モード: ファイル記述とテストデータでフォームを埋める際の確認をスキップ

品質基準

ドキュメントは以下の程度に優れている必要があります：

1. 新規ユーザーはガイドに従うことであらゆるタスクを完了できることなしにヘルプを求める必要がない
2. すべてのスクリーンショットが文脈を持つ — これは何を見ているのか？何をすべきか？
3. ステップはアトミック — 1 ステップにつき 1 アクション、「X をクリックしてから Y と Z を埋める」ではなく
4. Tips が隠れた価値を明かす — ショートカット、パワー機能、ユーザーが独自に発見できないもの
5. トラブルシューティングが実際 — 仮説的な FAQ ではなく、ドキュメント作成中に遭遇した実際の混乱する瞬間に基づく
6. スキャン可能 — 見出し、スクリーンショット、テーブル、Tips。誰もドキュメントをトップダウンで読むわけではありません。必要なものを検索します。