课程介绍

了解读者

为什么
- 保证文档可用性——可用文档：读者可以理解文档并借助文档完成任务
如何做
- 明确读者身份——小白、运维、开发？
- 明确读者阅读目的——了解概念？完成步骤、参数解释？
- 明确读者所需的信息——根据受众的认知能力提供所需信息。
反例：
- 开发写给运维的写的手册是讲自己的设计理念的，而运维只关心如何解决问题
了解读者
- 信息差（狭义）——作者与读者之间的认知差异，写作中应该尽量弥补信息差。
- 知识诅咒：越是了解一样东西，越是不了解不了解它的人的想法
常见信息差来源
- 术语
  - 使用标准的术语
  - 同一个意思尽量使用一个词表达
  - 提供术语解释提供解释链接或者提供悬浮解释
- 相似物
  - 一个产品提供了两个相似的功能，一般需要使用表格列出辨析，帮助读者选出合适的
- 新事物
  - 所有新事物都需要详细的解释和提供支持，否则影响客户满意、提升了后续的客户支持成本
如何了解读者
- 主动走进读者
  - 邀请同事评审
  - 读者访谈
  - 文档支持群
- 时常问自己
  - 读者从哪里来（读者想要做什么，需要什么）
  - 读者在哪里（读者跟随这篇文档的过程中，会面临什么情况）
  - 读者到哪里去（提供后续的进一步材料）

文档类型	描述	示例
概念性	介绍某一个概念，内容可以是价绍背景、原理以及优劣势等等	名词+名词，如《A概述》《A背景》《A原理》
任务型	指导完成某项具体的任务，内容通常包括业务背景、前置条件、操作步骤、验证结果以及注意事项	名词+动词或动词+名词，如《A工具的安装》《部署A环境》
参考型	罗列参考信息，比如产品型号参数、API参数以及配置参数等	名词+名词，如《机器配置的要求》