> ## Documentation Index
> Fetch the complete documentation index at: https://www.mintlify.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 如何了解你的文档受众

> 定义你的文档受众，研究他们的目标和知识水平，并将这些洞察应用到编写帮助他们成功的内容中。

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

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

<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 theme={null}
<!-- 为技术水平较低的受众在上下文中定义 -->
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>


## Related topics

- [如何衡量和提升文档质量](/zh/guides/improving-docs.md)
- [文档内容类型](/zh/guides/content-types.md)
- [如何构建文档导航结构](/zh/guides/navigation.md)