developer-docs-audience-research
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseDeveloper 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
在规划、撰写或重组文档前，可使用该技能明确开发者文档的目标受众。它能帮助Agent将模糊的受众群体转化为具体的用户、目标、问题、用户旅程及验证工作。
本技能源自Jared Bhatti、Zachary Sarah Corleissen、Jen Lambourne、David Nunez和Heidi Waterhouse所著的《Docs for Developers: An Engineer's Field Guide to Technical Writing》（《面向开发者的文档：技术写作工程师实战指南》），尤其参考了第1章“了解你的受众”。同时，结合了Christopher Gales及Splunk文档团队所著《The Product Is Docs: Writing Technical Documentation in a Product Development Group》（《产品即文档：产品开发团队技术写作指南》）中的相关指导内容，重点参考了第3章“受众”、第9章“学习目标”和第25章“SaaS文档写作”。请勿将书籍原文直接复制到用户输出中。来源：https://link.springer.com/book/10.1007/978-1-4842-7217-6
Quick Start
快速入门
- Load to choose the smallest useful reference set.
guidelines.md - Start from the user's doc artifact or product surface, not from a generic audience label.
- Identify user goals, learning objectives, business goals, user traits, questions, and missing knowledge.
- Use when the user needs a full audience brief.
workflows/map-doc-audience.md - Mark assumptions and recommend validation through user conversations, support data, analytics, or a friction log.
- 加载文件，选择最实用的参考集合。
guidelines.md - 从用户的文档工件或产品界面入手，而非通用的受众标签。
- 明确用户目标、学习目标、业务目标、用户特质、问题及知识缺口。
- 当用户需要完整的受众简报时，使用。
workflows/map-doc-audience.md - 标记假设内容，并建议通过用户访谈、支持数据、分析或摩擦日志进行验证。
Default Output
默认输出
When researching an audience, return:
- Audience snapshot - primary and secondary users, roles, skill level, environment, and constraints.
- Goals - user goals and business goals that the docs must support.
- Learning objective - starting point, destination, and exit criteria when useful.
- User questions - setup, concept, task, API, troubleshooting, and decision questions.
- Research artifacts - audience definition, persona, user story, journey map, or friction log entries when useful.
- Assumptions and gaps - what is inferred versus verified.
- Validation plan - the next interviews, data sources, or product walk-throughs.
开展受众研究时，需返回以下内容：
- 受众快照 - 主要及次要用户、角色、技能水平、使用环境及约束条件。
- 目标 - 文档需支持的用户目标与业务目标。
- 学习目标 - 适用情况下的起始水平、预期目标及完成标准。
- 用户问题 - 安装配置、概念理解、任务执行、API相关、故障排查及决策类问题。
- 研究工件 - 适用情况下的受众定义、用户画像、用户故事、旅程图或摩擦日志条目。
- 假设与缺口 - 推断内容与已验证内容的区分。
- 验证计划 - 后续访谈、数据源或产品演练安排。
Contents
目录
| Need | Start Here |
|---|---|
| Understand audience concepts | |
| Apply research rules | |
| See concise examples | |
| Produce an audience brief | |
| Define learning objectives | |
| Route by task | |
| 需求 | 起始参考 |
|---|---|
| 理解受众相关概念 | |
| 应用研究规则 | |
| 查看简洁示例 | |
| 生成受众简报 | |
| 定义学习目标 | |
| 按任务导航 | |
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.
- 在未按任务、场景、技能及环境细分前，“开发者”这一群体定义过于宽泛。
- 区分用户需求与内部团队的表达诉求。
- 区分持久的受众定义与特定的用户画像。
- 优先基于证据而非假设，但在暂无证据时需清晰记录假设内容。
- 根据受众研究结果及学习目标确定内容类型、顺序、深度、示例及成功指标。