documentation

使用するタイミング

Diátaxis フレームワークに従う技術ドキュメントの作成、レビュー、改善が必要な場合にこのスキルを使用してください。例えば以下のような場合です:

• ユーザーガイドの作成
• API ドキュメンテーション
• チュートリアルコンテンツ
• 既存ドキュメントの再構成（異なるユーザーニーズと文脈により良く対応するため）

手順

ドキュメントを4つの異なるタイプ（チュートリアル、ハウツーガイド、リファレンス資料、説明）に整理します。それぞれが異なるユーザーニーズと文脈に対応しています。

ドキュメント作成 前に、ユーザーの文脈、対象者、目標について必ず質問をして明確にしてください。

---

ステップ 1 — ドキュメントタイプを特定する

ユーザーのシグナルに基づいて以下の決定チェックリストを使用してください:

ユーザーシグナル	ドキュメントタイプ
「X を始めたばかりで学びたい」 / 「一通り説明してほしい」	チュートリアル
「どうやって...？」 / 「X を達成したい」	ハウツーガイド
「X のパラメータ/オプション/構文は？」	リファレンス
「なぜ X はこうなっているのか？」 / 「X を理解したい」	説明

クイック判断ツリー:

• ユーザーが 初めて実践しながら学んでいる のか？ → チュートリアル
• 既に理解している特定の問題を解決する 必要があるのか？ → ハウツーガイド
• 技術的な事実を調べる 必要があるのか？ → リファレンス
• 概念的な背景を知りたい のか？ → 説明

---

ステップ 2 — タイプ固有のパターンを適用する

チュートリアル（学習志向）

• タイトルパターン: 動詞で始める — 「初めての X を作る」、「Y をゼロから作成する」
• 構成: ゴール → 前提条件 → 段階的なステップ → 各ステップで検証可能な結果 → 最終成果
• 説明は最小限に、実践を最大限に
• すべてのステップで目に見える、テスト可能な結果を生み出す必要がある
• 検証: 初心者が外部の助けなしにチュートリアルを完了できること

例となる導入:

「このチュートリアルでは、Express を使用してシンプルな REST API を構築します。終了時には、GET リクエストに応答する実行中のサーバーが完成します。Express の事前知識は不要です。」

---

ハウツーガイド（問題志向）

• タイトルパターン: タスクとしてフレーム化 — 「X を設定する方法」、「Y を Z にデプロイする方法」
• 構成: ゴールステートメント → 前提/仮定 → 段階的なステップ → 期待される結果
• 基礎知識があることを前提とし、概念的な説明は省略
• バリエーションを認める、代替案が存在する場合は記載
• 検証: 経験のあるユーザーが混乱や手戻りなくタスクを完了できること

例となる導入:

「このガイドは、既存の Express アプリに JWT 認証を追加する方法を示しています。動作している Express サーバーと基本的なミドルウェアの知識があることを想定しています。」

---

リファレンス（情報志向）

• タイトルパターン: 対象を命名 — 「設定オプション」、「API エンドポイント」、「CLI フラグ」
• 構成: 各エントリーで一貫した反復可能な形式（名前 → 型 → デフォルト → 説明 → 例）
• 事実を述べ、最小限の使用例以外の指示は避ける
• 最新を保つ、必要に応じてバージョン記載
• 検証: ユーザーが周囲のコンテンツを読まずに30秒以内に特定の事実を調べられること

例となるエントリー:

timeout (整数、デフォルト: 5000) レスポンスを待つ最大時間（ミリ秒）。この時間を超えるとリクエストは失敗します。 例: { timeout: 3000 }

---

説明（理解志向）

• タイトルパターン: コンセプトとしてフレーム化 — 「X の仕組み」、「Y を理解する」、「Z がこのように設計されている理由」
• 構成: 文脈 → コア概念 → 代替案/トレードオフ → より高いレベルの視点
• ステップバイステップの指示や技術仕様は避ける
• 検証: 読了後、ユーザーが概念を自分の言葉で説明でき、設計上の決定の根拠を理解していること

例となる導入:

「認証と認可はしばしば混同されます。このページではこの区別を説明し、なぜ両方が重要なのか、そして一般的なパターン（セッション、トークン、OAuth）が各懸念事項にどのようにアプローチしているかを説明します。」

---

ステップ 3 — 分離と統合を維持する

• 各ドキュメントを単一のタイプにしておく — チュートリアルのステップとリファレンステーブルや概念的な脱線を混ぜない
• タイプ間でクロスリンクする：チュートリアルは関連するリファレンスページにリンク可能、ハウツーガイドは背景説明として説明ページにリンク可能
• すべてのタイプで一貫した見出しと用語を使用し、ユーザーがドキュメントシステム全体をナビゲートできるようにする

---

ステップ 4 — 配信前に検証する

タイプ	検証チェック
チュートリアル	初心者が外部の助けなしにエンドツーエンドで完了できるか？
ハウツーガイド	経験のあるユーザーにとって記載されている問題を解決するか？
リファレンス	ユーザーが特定の事実を30秒以内に見つけられるか？
説明	ユーザーが「何か」だけでなく「なぜか」を理解しているか？