developer-docs-audience-research

Developer Docs Audience Research

Use this skill to understand who developer documentation is for before planning, writing, or reorganizing docs. It helps agents turn vague audiences into concrete users, goals, questions, journeys, and validation work.

This skill is derived from Jared Bhatti, Zachary Sarah Corleissen, Jen Lambourne, David Nunez, and Heidi Waterhouse's Docs for Developers: An Engineer's Field Guide to Technical Writing, especially Chapter 1, "Understanding your audience." It is expanded with paraphrased guidance from Christopher Gales and the Splunk Documentation Team's The Product Is Docs: Writing Technical Documentation in a Product Development Group, especially Chapter 3, "Audience," Chapter 9, "Learning Objectives," and Chapter 25, "Writing SaaS Documentation." Do not copy book prose into user outputs. Source: https://link.springer.com/book/10.1007/978-1-4842-7217-6

Quick Start

1. Load guidelines.md to choose the smallest useful reference set.
2. Start from the user's doc artifact or product surface, not from a generic audience label.
3. Identify user goals, learning objectives, business goals, user traits, questions, and missing knowledge.
4. Use workflows/map-doc-audience.md when the user needs a full audience brief.
5. Mark assumptions and recommend validation through user conversations, support data, analytics, or a friction log.

Default Output

When researching an audience, return:

1. Audience snapshot - primary and secondary users, roles, skill level, environment, and constraints.
2. Goals - user goals and business goals that the docs must support.
3. Learning objective - starting point, destination, and exit criteria when useful.
4. User questions - setup, concept, task, API, troubleshooting, and decision questions.
5. Research artifacts - audience definition, persona, user story, journey map, or friction log entries when useful.
6. Assumptions and gaps - what is inferred versus verified.
7. Validation plan - the next interviews, data sources, or product walk-throughs.

Contents

| Need | Start Here |

|------|------------|

| Understand audience concepts | references/core/knowledge.md |

| Apply research rules | references/core/knowledge.md |

| See concise examples | references/core/knowledge.md |

| Produce an audience brief | workflows/map-doc-audience.md |

| Define learning objectives | workflows/define-learning-objectives.md |

| Route by task | guidelines.md |

Core Posture

• Treat "developer" as too broad until narrowed by task, context, skill, and environment.
• Separate what users need from what internal teams want to say.
• Distinguish durable audience definitions from specific personas.
• Prefer evidence over assumptions, but preserve assumptions clearly when evidence is not available yet.
• Let audience findings and learning objectives shape content type, order, depth, examples, and success metrics.