developer-docs-audience-research

开发者文档受众研究

在规划、编写或重组文档之前，使用此技能了解开发者文档面向哪些人。它可以帮助 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 Documentation Team 所著 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

快速开始

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

核心原则

• 在明确任务、背景、技能和环境之前，不要将“开发者”视为足够具体的受众。
• 将用户的需求与内部团队想表达的内容区分开来。
• 区分长期有效的受众定义和具体的用户画像。
• 优先采用证据而非假设；如果暂时没有证据，也要清楚保留假设。
• 根据受众研究结果和学习目标来确定内容类型、顺序、深度、示例和成功指标。