developer-docs-audience-research

開発者向けドキュメントの対象読者調査

ドキュメントの計画、執筆、再構成を始める前に、開発者向けドキュメントが誰を対象としているのかを理解するために、このスキルを使用してください。漠然とした対象読者を、具体的なユーザー、目標、疑問、利用の流れ、検証作業へと落とし込むのに役立ちます。

このスキルは、Jared Bhatti、Zachary Sarah Corleissen、Jen Lambourne、David Nunez、Heidi Waterhouseによる Docs for Developers: An Engineer's Field Guide to Technical Writing、特に第1章「Understanding your audience」に基づいています。また、Christopher GalesとSplunk Documentation Teamによる The Product Is Docs: Writing Technical Documentation in a Product Development Group、特に第3章「Audience」、第9章「Learning Objectives」、第25章「Writing SaaS Documentation」から、言い換えた指針を加えています。ユーザー向けの出力に書籍の文章をそのまま引用しないでください。出典：https://link.springer.com/book/10.1007/978-1-4842-7217-6

クイックスタート

1. guidelines.md を読み込み、役立つ最小限の参考資料セットを選びます。
2. 一般的な対象読者の分類ではなく、ユーザーが扱うドキュメントの成果物や製品の利用箇所から始めます。
3. ユーザーの目標、学習目標、ビジネス目標、ユーザーの特性、疑問、不足している知識を特定します。
4. ユーザーが詳細な対象読者ブリーフを必要とする場合は、workflows/map-doc-audience.md を使用します。
5. 仮定を明示し、ユーザーとの会話、サポートデータ、分析データ、または摩擦ログを通じた検証を提案します。

デフォルトの出力

対象読者を調査する際は、次の内容を提示します。

1. 対象読者の概要 — 主なユーザーと副次的なユーザー、役割、スキルレベル、環境、制約。
2. 目標 — ドキュメントが支援すべきユーザーの目標とビジネス目標。
3. 学習目標 — 必要に応じて、開始時の状況、到達点、完了条件。
4. ユーザーの疑問 — セットアップ、概念、タスク、API、トラブルシューティング、意思決定に関する疑問。
5. 調査成果物 — 必要に応じて、対象読者の定義、ペルソナ、ユーザーストーリー、ジャーニーマップ、摩擦ログの項目。
6. 仮定と不足点 — 推測した内容と検証済みの内容の区別。
7. 検証計画 — 次に行うインタビュー、参照するデータソース、または製品のウォークスルー。

目次

必要な内容	参照先
対象読者の概念を理解する	references/core/knowledge.md
調査のルールを適用する	references/core/knowledge.md
簡潔な例を見る	references/core/knowledge.md
対象読者ブリーフを作成する	workflows/map-doc-audience.md
学習目標を定義する	workflows/define-learning-objectives.md
タスクに応じて参照先を選ぶ	guidelines.md

基本姿勢

• タスク、状況、スキル、環境によって絞り込むまでは、「開発者」という分類は広すぎるものとして扱います。
• ユーザーが必要としている内容と、社内チームが伝えたい内容を分けます。
• 長期的に有効な対象読者の定義と、特定のペルソナを区別します。
• 仮定より根拠を優先します。ただし、根拠がまだ得られていない場合は、仮定を明確に残します。
• 対象読者の調査結果と学習目標に基づいて、コンテンツの種類、順序、詳細さ、例、成功指標を決めます。