documentation

使用する場面

Diátaxis フレームワークに沿って技術ドキュメントを作成、レビュー、改善する必要がある場合に、このスキルを使用します。例：

• ユーザーガイドの作成
• API ドキュメント
• チュートリアルのコンテンツ
• さまざまなユーザーのニーズや状況によりよく応えられるよう、既存ドキュメントを再構成する

手順

ドキュメントを、チュートリアル、ハウツーガイド、リファレンス資料、解説という4つの明確なタイプに整理します。それぞれ異なるユーザーのニーズや状況に応えるものです。

ドキュメントを作成する前に、ユーザーの状況、対象読者、目標について必ず確認の質問をしてください。

---

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

ユーザーの発言をもとに、次の判断チェックリストを使用します。

ユーザーの発言	ドキュメントのタイプ
「X は初めてなので、学びたいです」／「順を追って説明してください」	チュートリアル
「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 秒以内に見つけられますか？
説明	ユーザーは「何を」だけでなく「なぜ」も理解できますか？