如何了解你的文档受众

识别你的文档受众，研究他们的目标和知识水平，并编写帮助他们成功的内容。

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

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

​

定义你的主要受众

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

常见的文档受众包括：

• 新用户，第一次学习产品，需要指导、背景和逐步引导
• 集成你的 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.

​

将术语与受众的词汇匹配

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

​

根据任务调整深度和结构

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

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

​

将受众意识融入你的流程

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

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

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

​

常见问题

如果我的文档服务于多个受众怎么办？

为每个页面确定主要受众，而不是试图在同一内容中服务所有人。对于拥有真正不同受众的产品——具有不同目标和知识水平的独立画像——考虑是否需要单独的文档部分或导航路径。Mintlify 支持基于标签页的导航，可以按受众分离内容，而无需完全独立的文档站点。

如何同时为技术用户和非技术用户编写文档？

为每类用户创建单独的内容，而不是试图混合它们。面向非技术决策者的概念解释和面向集成你产品的开发者的 API 参考服务于不同的目的，应该是不同的页面。在重叠不可避免的地方，偏向更技术的版本，并为需要的读者链接到更简洁的概念内容。

我应该多久重新审视一次对受众的假设？

当你发布重大产品变更时，当你的用户群体发生显著变化时，或者当支持工单模式以与现有文档不匹配的方式变化时。每季度审查搜索分析和反馈数据有助于发现偏差。与支持团队更频繁的沟通可以更快地发现它。

识别文档空白最快的方法是什么？

问你的支持团队他们最常处理的、在文档中没有很好覆盖的主题是什么。这比任何分析工具都能更快地揭示高影响力的空白。用户访谈、显示无结果查询的搜索分析，以及显示用户浏览页面但找不到答案的会话回放，都能从那里增加更多深度。