diataxis

Diataxis メソッドでドキュメントを管理する

Diataxis フレームワークに沿って、ユーザーがプロジェクトのドキュメントを整理し、管理できるよう支援します。

Diataxis とは？

Diataxis（古代ギリシャ語の dia —「横断する」、taxis —「配置する」に由来）は、ユーザーのニーズに基づいてコンテンツを 4 つのカテゴリに分類する、技術ドキュメントへの体系的なアプローチです。フレームワークの詳細については、diataxis.fr をご覧ください。

カテゴリ	指向	目的	形式
チュートリアル	学習指向	初心者が学べるように案内する	レッスン
ハウツーガイド	タスク指向	特定の目標の達成を支援する	一連の手順
解説	理解指向	議論を通じて理解を深める	論述的なエッセイ
リファレンス	情報指向	正確な技術情報を提供する	簡潔で正確な事実

コンパス — 分類のための 2 つの軸

次の 2 つの質問を使って、あらゆるコンテンツを分類します（references/compass.md を参照）。

	習得（学習）	適用（作業）
行動（実践的）	チュートリアル	ハウツーガイド
認知（理論的）	解説	リファレンス

1. 「これは行動に関するものですか、それとも認知に関するものですか？」 — 読者が何かを行うのか、それとも何かを理解するのかを確認します。
2. 「これは習得に関するものですか、それとも適用に関するものですか？」 — 読者は学習中なのか、それとも作業中なのかを確認します。

主な違い

• チュートリアルとハウツーガイド：チュートリアルは学習者に「一緒に進みましょう」と教えます。ハウツーガイドは実務者に「これを行ってください」と指示します。チュートリアルは最初から最後まで完結しています。ハウツーガイドは、読者が自分の作業に取り入れられる適切な区切りから始まり、終わります。
• 解説とリファレンス：解説は理由を論じます（論述的で、意見を含みます）。リファレンスは事実を述べます（簡潔で権威があり、曖昧さがありません）。
• 行動と認知：チュートリアルとハウツーガイドは実践的なもの（行うこと）です。解説とリファレンスは理論的なもの（知ること）です。
• 習得と適用：チュートリアルと解説は学習や勉強に役立ちます。ハウツーガイドとリファレンスは作業やコーディングに役立ちます。

ステップ 1：既存のドキュメントを探す

1. プロジェクト内のドキュメントファイルを確認します。

   • docs/、doc/、documentation/ ディレクトリを探します。
   • プロジェクトのルートにある Markdown ファイルを確認します：README.md、CONTRIBUTING.md、CHANGELOG.md
   • その他のドキュメント形式を探します：.rst、.adoc、.txt
   • ドキュメントの設定ファイルを確認します：mkdocs.yml、docusaurus.config.js、conf.py、antora.yml、hugo.toml

2. 既存のドキュメントを読んで、すでに扱われている内容を把握します。

3. ドキュメントが存在しない場合：

   • ユーザーに「ドキュメントが見つかりませんでした。ドキュメント構成を一から作成しましょう。」と伝えます。
   • ステップ 3：ドキュメント構成を提案する に進みます。

ステップ 2：既存のドキュメントを分類する

各ドキュメントページを分析し、Diataxis の 4 つのカテゴリのいずれかに分類します。

以前の分類判断を尊重する

再分類を提案する前に、意図的な過去の変更がないか、Git の履歴を確認します。

git log --all --oneline --diff-filter=R -- 'docs/**/*.md'

ファイルがカテゴリ間で意図的に移動されていた場合（たとえば、コミットメッセージが docs(diataxis): reclassify X as reference のような場合）は、ユーザーが明示的に再検討を求めない限り、その判断を尊重してください。過去に意図的に行われた再分類は、コンパスだけでは捉えられない判断を反映している可能性があります。これを覆すのではなく、ユーザーに伝えてください。

分類ルール

分類の質問と以下のシグナルを使用してください。各カテゴリの詳しい記述ガイドラインについては、 references/ 内の参考ファイルを参照してください。

次の条件を満たすページは、チュートリアルです（references/tutorials.md を参照）：

• 執筆者のガイドに沿って、初心者が一連の学習を完了できるように導いている
• 明確な開始地点と最終目標があり、各ステップで目に見える成果が得られる
• 一人称複数形を使っている：「このチュートリアルでは、〜します」「まず x を実行します。次に、y を実行します」
• 読者が実際に手を動かしながら学ぶ、順を追った構成になっている
• 実社会の課題を解決することではなく、知識の習得に重点を置いている
• 説明は最小限にし、話が脱線する代わりにリンク先を案内している

次の条件を満たすページは、ハウツーガイドです（references/how-to-guides.md を参照）：

• ツールではなく、ユーザーの視点から具体的な目標を扱っている
• 読者がすでに基本的な知識を持ち、何をしたいかを理解している前提である
• 正確なタイトルを使用している：「モニタリングを統合する方法」。単に「モニタリング」とはしない
• 実行可能な解決策を提示している：「この状況に直面した場合は、以下の手順に従ってください」
• 適切な開始点と終了点があり、読者が自分の作業に組み込める
• 概念を教えたり、リファレンステーブルを含めたりせず、実践的な内容にとどめている

次の条件を満たすページは、解説です（references/explanation.md を参照）：

• 概念、背景、設計上の判断、トレードオフについて論じている
• 「〜について教えてください」という問いに答えている。タイトルの先頭に暗黙の「〜について」が付く
• 概念同士のつながりを示し、背景（歴史、理由、代替案など）を説明している
• 複数の視点を認め、意見を述べながら比較検討する、論述的な文章を使用している
• キーボードから離れた場所で読んでも理解できる
• 手順やリファレンス資料を取り込むことを避けている

次の条件を満たすページは、リファレンスです（references/reference.md を参照）：

• API、設定、CLI フラグ、データ構造を権威ある形で説明している
• 参照用に構成されている（最初から最後まで通読するものではない）
• 簡潔で事実に基づき、正確である。事実を断定的な表現で示している
• 説明対象の仕組みの構造を反映している
• すべての項目で、一貫した標準的なパターンを使用している
• 使い方を教えることなく、使用例を示す最小限の例を提供している

複数カテゴリが混在する内容

多くのページには複数のカテゴリに属する内容が含まれています。その場合はユーザーに指摘し、分割方法を提案してください：

• 「このページには、チュートリアルの内容（はじめにのセクション）とリファレンスの内容（API テーブル）が混在しています。チュートリアルページとリファレンスページに分割することを検討してください。」

境界事例

一部のコンテンツ形式は、分類の境界に位置します。分類の基準を機械的に適用せず、 ページの構成と想定される使い方を考慮してください：

• トラブルシューティング：症状、原因、修正方法をまとめた参照用の表は、リファレンスです （参照しやすいように構成され、問題の構造を反映し、事実を簡潔に示しているためです）。段階的に診断プロセスを進めるページは、 ハウツーです（目標に向けた手順になっているためです）。 カテゴリを決めるのは形式であり、題材ではありません。
• FAQ ページ：個々の Q&A 項目は、多くの場合リファレンスです（参照用）。理解を深めるように編集された FAQ は、解説です。
• 移行ガイド：段階的なアップグレード手順は、ハウツーです。変更点とその理由についての説明は、解説です。

境界事例の判断に迷った場合は、次の点を考慮してください。読者はこのページをどのように使うでしょうか？ 参照するために読む → リファレンス。手順に沿って進める → ハウツー。

分類結果の提示

結果は表で提示してください：

| File                     | Current Category | Suggested Category | Notes              |
|--------------------------|------------------|--------------------|--------------------------------|
| docs/getting-started.md  | -                | Tutorial           | Good tutorial structure         |
| docs/api.md              | -                | Reference          | Contains some how-to content   |
| docs/architecture.md     | -                | Explanation        | Well-structured explanation     |

ステップ 3：ドキュメント構成を提案する

分析に基づいて、Diataxis に沿ったディレクトリ構成を提案してください。

標準ディレクトリレイアウト

docs/
  tutorials/           # Learning-oriented
    getting-started.md
    first-project.md
  how-to/              # Task-oriented
    install.md
    configure.md
    deploy.md
  explanation/         # Understanding-oriented
    architecture.md
    design-decisions.md
  reference/           # Information-oriented
    api.md
    configuration.md
    cli.md

適応ルール

• 既存のツールに適応する：プロジェクトで mkdocs、docusaurus、antora、hugo などを使用している場合は、そのツールの規約に沿った構成を提案します。
• 既存の構成に適応する：プロジェクトに Diataxis と部分的に一致するドキュメント構成がすでにある場合は、全面的に再構成するのではなく、完全に整合させるための最小限の変更を提案します。
• 機能しているものは維持する：すでに適切に分類されているコンテンツの移動は提案しません。
• プロジェクトの規約を尊重する：プロジェクトで特定の命名規則（kebab-case、snake_case など）を使用している場合は、それに従います。

ドキュメントの不足を特定する

既存のコンテンツを分類した後、不足している項目を特定します。

• チュートリアルがない場合：入門チュートリアルの作成を提案します。
• ハウツーガイドがない場合：よく使われるタスク（インストール、設定、デプロイ）向けのガイドを提案します。
• 解説がない場合：アーキテクチャや設計上の決定に関するドキュメントを提案します。
• リファレンスがない場合：API、設定、CLI のリファレンスページを提案します。

不足項目を明確に示します。

Documentation gaps identified:
- [ ] Missing: Tutorial for getting started
- [ ] Missing: How-to guide for deployment
- [ ] Missing: Reference for configuration options
- [x] Covered: Architecture explanation exists

ステップ 4：変更を実行する

**変更を行う前に、必ずユーザーに確認してください。**計画を提示し、承認を待ちます。

再構成する場合

1. 移動および名前変更を予定しているファイルを提示します
2. ユーザーの承認を待ちます
3. ファイルを新しい場所に移動します
4. ドキュメントページ間の内部リンクを更新します
5. 該当する場合はナビゲーション設定（mkdocs.yml、サイドバー設定など）を更新します
6. リンク切れがないことを確認します

新しいページを作成する場合

1. 作成を提案するページを提示します
2. ユーザーの承認を待ちます
3. references/templates.md にある該当カテゴリ用のテンプレート（チュートリアル、ハウツーガイド、解説、リファレンス）を使って、適切な構成でページを作成します
4. プロジェクトの分析結果（ソースコード、既存のドキュメント、設定ファイル）に基づいて内容を記入します

既存のページを改善する場合

ページがすでに適切なカテゴリに分類されているものの、Diataxis の原則により沿うために改善が必要な場合：

1. 具体的な問題（内容の混在、不適切な文体、構成の不足）を特定します
2. 提案する変更をユーザーに提示します
3. 承認後に変更を適用します

重要なガイドライン

• フレームワークを無理に適用しない：プロジェクトが小規模で、README ひとつですべてを十分に説明できる場合は、その旨を伝えます。Diataxis が最も役立つのは、ドキュメントが相当量あるプロジェクトです。
• 現実的に進める：ある程度整理されたドキュメントは、ドキュメントがない状態より優れています。完璧さを求めるのではなく、段階的な改善を提案します。
• コンテンツを保持する：再構成する場合でも、コンテンツを削除してはいけません。移動や整理は行いますが、既存の情報はすべて保持します。
• リンクを維持する：ファイルを移動する際は、すべての相互参照とナビゲーション設定を更新します。
• ユーザーの判断を尊重する：分類や再構成の提案にユーザーが同意しない場合は、その判断を受け入れ、提案を調整します。
• 品質への意識：Diataxis は品質向上に役立ちますが、品質を保証するものではありません。正確性、完全性、優れた文章は、引き続き著者の責任です。品質の観点については、references/quality.md を参照してください。
• 判断に迷ったらコンパスを使う：分類が不明確な場合や、文章を書くのが難しい場合は、コンパスの2つの質問を適用します。references/compass.md を参照してください。

参考ドキュメント

各カテゴリの詳細な執筆ガイドラインは、diataxis.frから抜粋しています。

• references/tutorials.md — 教育上の原則、言語表現の慣例、アンチパターン
• references/how-to-guides.md — 執筆の原則、対象範囲、チュートリアルとの違い
• references/explanation.md — 特徴、議論の領域、命名テスト
• references/reference.md — 簡潔さの原則、構造の対応、例
• references/compass.md — 分類のための2軸判断ツール
• references/quality.md — 機能面と本質面の品質基準