第2课：读者分析

为什么读者分析如此重要？

技术写作的第一步不是动笔，而是理解你的读者。一份优秀的文档，如果给错了人，就是无效文档。读者分析是技术写作中最容易被忽视、却最关键的步骤。很多文档质量不佳的根本原因，不是写作者能力不够，而是根本没想清楚在写给谁看。

写作的本质是沟通，沟通的前提是理解对方。——技术写作黄金法则

读者分类框架

按角色分类

不同的角色对技术文档有完全不同的需求。一个运维工程师需要的文档，和一个产品经理需要的文档，在内容、深度和格式上都截然不同。理解角色分类是读者分析的第一步。

按知识水平分类

同一角色的读者，知识水平也可能差异巨大。一个有10年经验的开发者和一个刚毕业的开发者，面对同一份API文档，理解和需求完全不同。你需要考虑知识水平光谱上不同位置的读者。

# 读者知识水平光谱

初学者 ──────────────────────────────────── 专家

  │                                              │

  │  需要背景知识    能理解术语    需要深层细节    │

  │  需要示例        能看代码      需要边界情况    │

  │  需要图示        能推断隐含    需要性能数据    │

  │                                              │

  └── 写作策略必须根据读者位置调整 ──────────────┘

读者画像方法

方法一：读者角色卡

读者角色卡是虚构一个代表性读者，详细描述其背景、需求和痛点。这个方法的核心价值在于：当你写作时，可以始终问自己"小明能看懂这段吗？"，比抽象的"读者"更容易做出正确判断。

# 读者角色卡模板

## 角色：初级后端开发者

- 姓名：小明（虚构代表）

- 经验：1-2年Java/Python开发

- 熟悉：REST API、数据库、Git

- 不熟悉：消息队列、容器编排、监控

- 目标：5分钟内跑通SDK的Hello World

- 痛点：环境配置容易出错，看不懂抽象概念

- 阅读习惯：先看示例代码，再读文字说明

- 可用时间：碎片化，不超过30分钟

方法二：读者旅程地图

读者旅程地图追踪读者从"发现问题"到"解决问题"的完整路径。它不仅记录读者做什么，还记录读者的情绪变化——这在设计文档体验时至关重要。

# 开发者使用API的旅程

1. 发现 ──→ "我需要解决什么问题？"

   需求：搜索到相关文档

   情绪：好奇但不确定



2. 评估 ──→ "这个方案适合我吗？"

   需求：快速理解核心概念和能力

   情绪：期待但怀疑



3. 试用 ──→ "5分钟能跑起来吗？"

   需求：Hello World级别的快速入门

   情绪：如果成功→兴奋；如果失败→挫败



4. 集成 ──→ "怎么在我的项目中使用？"

   需求：详细API参考、错误处理

   情绪：专注但容易焦虑



5. 深入 ──→ "如何优化和扩展？"

   需求：最佳实践、性能指南

   情绪：自信但追求更好

方法三：读者访谈

直接与目标读者对话，了解他们的真实需求。访谈是最直接也最被忽视的读者分析方法。很多写作者觉得自己"已经了解读者"，但实际访谈的结果往往让人意外。

针对不同读者的写作策略

策略一：分层写作

同一主题，为不同层次的读者提供不同深度的内容。这是处理多读者群体的最佳方式，也是"渐进展开"原则在读者分析中的具体应用。

# 分层写作示例：解释"缓存"

## TL;DR（管理者 / 快速浏览）

缓存把常用数据存在快速存储中，减少数据库查询，

页面加载速度提升3-5倍。



## 核心概念（初级开发者）

缓存就像你把常用的书放在桌面，而不是每次都去书架取。

我们使用Redis作为缓存，热点数据查询从200ms降到5ms。



## 深入理解（高级开发者）

Redis 7.x 缓存策略：

- 缓存穿透：布隆过滤器 + 空值缓存

- 缓存击穿：互斥锁 + 热点预加载

- 缓存雪崩：随机过期 + 多级缓存

- 一致性：Cache-Aside + 延迟双删 + Canal监听

策略二：入口路由

在文档首页提供明确的入口，让不同读者快速找到自己的路径。就像商场的楼层导览，让每个人第一时间知道该去哪里。入口路由的核心是"不浪费任何人的时间"。

# 文档首页路由示例

📖 我是谁？

  ├── 我是产品用户 → [快速入门指南]

  ├── 我是开发者   → [API文档]

  ├── 我是运维     → [部署手册]

  └── 我是管理者   → [产品白皮书]

策略三：渐进披露

先显示必要信息，将高级选项和细节折叠或放在独立章节。这减少了初次阅读的认知负担，同时保留了深度信息。渐进披露的精髓是：让每个人都能开始阅读，但不强迫任何人阅读他们不需要的内容。

多读者文档的常见陷阱

陷阱1：写给所有人 = 没人看

陷阱2：假设读者已知

陷阱3：知识诅咒

专家难以回忆初学时的困惑，会不自觉地跳过"显而易见"但新手并不清楚的步骤。这是技术写作中最隐蔽也最常见的错误。解决方法是：写完后请一个非本领域的同事试读，记录他们卡住的地方。

读者分析实战：案例分析

一个开源CLI工具的README可能同时被评估者、试用者、集成者、贡献者看到。他们的停留时间从30秒到1小时以上不等。因此README的结构必须按优先级排列，让不同读者各取所需。

读者分析的量化方法

# 利用分析数据理解读者

页面浏览量（PV）──→ 哪些主题最受关注

停留时间 ────────→ 内容是否满足需求

跳出率 ──────────→ 入口页是否有效

搜索关键词 ──────→ 读者在找什么

反馈评分 ────────→ 内容质量指标



# 示例分析

API Reference 页面 PV 最高 → 开发者是主要读者

Quick Start 跳出率 60% → 入门体验需要改进

搜索词 "配置SSL" 频率高 → SSL文档缺失或难找