diataxis-organize-docs

Diataxis によるドキュメントの整理

コンテンツを Diataxis のカテゴリに分類し、階層構造を持つドキュメントを作成して、ドキュメントを再編成します。

ドキュメントのカテゴリ

象限	指向	目的	ユーザーのニーズ
チュートリアル	学習	実践を通じて教える	「学びたい」
ハウツー	タスク	特定の問題を解決する	「X を達成したい」
リファレンス	情報	仕組みを説明する	「Y に関する事実を知りたい」
解説	理解	概念を明確にする	「なぜなのかを理解したい」

ディレクトリ構成

必要に応じてトピック別のサブディレクトリを追加し、ドキュメントを次の階層に整理します。

docs/
├── tutorial/            # Learning-oriented
│   ├── getting-started/
│   └── {topic}/
├── how-to/              # Task-oriented
│   ├── {task-category}/
│   └── troubleshooting/
├── reference/           # Information-oriented
│   ├── api/
│   ├── configuration/
│   └── architecture/
├── explanation/         # Understanding-oriented
│   ├── concepts/
│   ├── decisions/
│   └── background/
└── README.md            # Navigation hub

ルートナビゲーションファイルには常に docs/README.md を使用し、index.md は使用しないでください。

執筆規則

スキルの手順と生成されるドキュメントには、手動で管理する合計数や番号付きのセクション参照を含めないでください。説明的な見出しと名前付きリンクを使用してください。順序付きの手順では、レンダラーが番号を維持できるように、各 Markdown リストマーカーに 1. を使用してください。対象を理解したり使用したりするうえで必要な数値情報は保持してください。

ワークフロー

現在のタスクに必要なリファレンスのみを読み込みます。

1. 既存のコンテンツを分析します。 読者のニーズに基づいて、各ファイルまたはセクションを分類します。既存のコンテンツを分類する場合や、カテゴリが曖昧な場合は、分類基準を参照してください。
2. 構造を割り当てます。 コンテンツを上記の階層に割り当て、どのドキュメントを維持、移動、分割するかを特定します。
3. 複数の目的が混在するドキュメントを分割します。 ドキュメントが複数の目的に対応している場合は、移行手順と例について分割のガイダンスを参照してください。文脈を維持し、各象限にまたがる関連コンテンツをリンクします。
4. ナビゲーションを構築します。 ドキュメントハブを作成または更新する場合は、テンプレートについてナビゲーションのガイダンスを参照してください。コンテンツの移動や分割によって影響を受けるリンクを更新します。
5. 検証して報告します。 以下の完了チェックを適用します。監査の場合は、現在の状態、分類、配置予定のファイル、必要な相互参照を報告します。編集を完了した場合は、変更内容と検証結果を要約します。タスクに応じた分量で報告します。

完了チェック

• 各ドキュメントが1つの目的に対応している
• チュートリアルに明確な学習目標がある
• ハウツーガイドが特定の問題を解決している
• リファレンスが完全かつ正確である
• 解説が真の洞察を提供している
• 相互参照が関連コンテンツを結び付け、移動後も正しく機能する
• docs/README.md がユーザーの目的を明確にしている
• 孤立、重複、または失われたコンテンツがない