mintlify__docs/zh/guides/understand-your-audience.mdx

---
title: "如何了解你的文档受众"
sidebarTitle: "了解你的受众"
description: "定义你的文档受众，研究他们的目标和知识水平，并将这些洞察应用到编写帮助他们成功的内容中。"
keywords: ["文档受众", "用户研究", "受众画像", "技术写作受众", "用户反馈"]
---

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

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

<div id="define-your-primary-audience">
## 定义你的主要受众
</div>

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

常见的文档受众包括：

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

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

<div id="research-your-users">
## 研究你的用户
</div>

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

<div id="talk-directly-to-users">
### 直接与用户交流
</div>

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

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

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

<div id="embed-with-your-support-team">
### 融入你的支持团队
</div>

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

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

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

<div id="use-feedback-mechanisms">
### 使用反馈机制
</div>

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

<div id="observe-real-navigation-behavior">
### 观察真实的导航行为
</div>

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

<div id="apply-what-you-learn">
## 应用你学到的知识
</div>

<div id="write-to-the-right-knowledge-level">
### 针对正确的知识水平写作
</div>

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

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

```mdx
<!-- 为技术水平较低的受众在上下文中定义 -->
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.
```

<div id="match-terminology-to-your-audiences-vocabulary">
### 将术语与受众的词汇匹配
</div>

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

<div id="adjust-depth-and-structure-to-the-task">
### 根据任务调整深度和结构
</div>

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

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

<div id="build-audience-awareness-into-your-process">
## 将受众意识融入你的流程
</div>

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

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

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

<div id="frequently-asked-questions">
## 常见问题
</div>

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

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

<Accordion title="我应该多久重新审视一次对受众的假设？">
当你发布重大产品变更时，当你的用户群体发生显著变化时，或者当支持工单模式以与现有文档不匹配的方式变化时。每季度审查搜索分析和反馈数据有助于发现偏差。与支持团队更频繁的沟通可以更快地发现它。
</Accordion>

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