如何了解你的文档受众

为所有人编写的文档往往对任何人都没有用。最清晰、最准确的内容如果假设了错误的知识水平、使用了不熟悉的术语或针对读者不具备的目标，仍然会失败。

了解你的受众是有效文档的基础。本指南涵盖了如何定义你的写作对象、如何通过研究了解他们，以及如何将这些洞察应用到你的内容中。

每个页面都要为一种特定类型的读者编写。当你试图在同一内容中服务多个受众时，你最终会做出妥协——添加让专家感到无聊的初学者背景，或假设让初学者迷失的知识。

常见的文档受众包括：

• 新用户，第一次学习产品，需要指导、背景和逐步引导
• 集成你的 API 的开发者，需要技术准确性、代码示例和参考资料——而不是一般性解释
• 配置产品的管理员，需要关于设置、权限和边缘情况的具体信息
• 评估产品的技术决策者，需要架构概述、安全信息和功能摘要

在编写任何页面之前，问自己：谁在阅读这个，他们试图完成什么？这两个问题决定了随后的每一个决策——结构、深度、语气、术语以及要省略什么。

不要依赖对受众的假设。内部团队对自己的产品有太多的背景知识，无法成为用户的可靠代理。

用户访谈能揭示分析工具无法提供的洞察。问用户：

• 他们用自己的话如何描述你的产品的功能？
• 他们上次查阅文档时试图完成什么？
• 他们觉得什么令人困惑或缺失？
• 他们用什么术语来称呼你的产品所做的事情？

最后一个问题对文档特别有价值。如果用户将你的功能称为”webhook”，而你在文档中称之为”event callback”，搜索帮助的用户将找不到你的内容——即使找到了也不会认为它是相关的。

支持团队不断看到文档的失败之处。问他们：

• 哪些主题产生了最多的工单？
• 用户最常在哪里感到困惑或卡住？
• 用户说他们期望找到但找不到什么？

这通常是找到影响最大的文档空白的最快方式。

给读者提供一种方式来表示某些内容不起作用。文档页面上的点赞/点踩评分和开放式评论字段可以揭示哪些内容有效、哪些无效。高流量页面上的负面反馈是高优先级的修复事项。请参阅改进你的文档了解更多关于使用反馈数据的信息。

像 FullStory 和 Hotjar 这样的会话回放工具可以准确显示用户如何浏览你的文档。他们在哪里停顿、在哪里向上滚动以及在哪里放弃会话，揭示了用户通常不会直接报告的空白。

根据你的受众已经知道的内容来校准你的解释——而不是你的团队知道的内容。

集成你的 API 的开发者不需要你解释什么是 API。配置你的企业产品的非技术管理员可能需要。在首次引入技术术语时进行定义，并链接到更深入的解释，而不是在每个页面中都插入基础背景内容。

<!-- 为技术水平较低的受众在上下文中定义 -->
Your API key—a unique token that identifies your account—must be included in every request.

<!-- 为开发者受众跳过基础内容 -->
Include your API key in the Authorization header of every request.

使用你的用户使用的词汇。如果你的用户将某物称为”项目”，而你的产品将其称为”工作区”，那么你的文档对于那些尚未内化你内部词汇的人来说会感觉陌生。用用户搜索的术语来记录事物，然后在旁边介绍你的产品术语。

处于不同阶段的受众有不同的需求：

• 新用户需要指导和安心——清晰的里程碑、有限的选择以及频繁确认他们在正确的轨道上
• 有经验的用户需要快速浏览——一致的结构、密集的信息、最少的背景
• 参考文档的读者最需要的是完整性

了解你的受众不是一次性的工作。产品在变化，受众在演变，新的用户群体在出现。

以下一些实践可以保持受众理解的时效性：

• **在发布前让支持团队成员审查新页面。**他们会迅速发现假设可能不成立的地方。
• **在写作简报中包含受众假设。**声明”本页面面向已完成身份验证的开发者”可以在审查过程中保持写作的针对性。
• **将新员工作为代理。**在他们内化你产品的内部词汇之前，让他们仅使用文档完成一项任务。他们的体验通常反映了新用户的体验。