这是我参与「第五届青训营 」伴学笔记创作活动的第10天
【写作前】了解读者
【写作中】结构化写作，写好标题，极简写作
【写作后】检查文档
了解读者
了解目标读者实际的需求，定位写作目标，避免“自嗨式”写作。
了解读者【为什么】
保证文档可用性：帮助读者理解文档，并能够顺利完成任务
了解读者【是什么】
明确读者身份：小白用户 or 资深用户？运维人员 or 开发人员？
明确读者阅读目的：了解一个概念、完成一个步骤，还是查阅一个参数解释？
明确读者所需信息：根据读者的认知能力提供所需信息。
信息差/信息不对称
作者和读者之间的认知差异
The curse of knowledge 知识诅咒/知识陷阱：要对普通用户、没有专业知识的人有同理心 → 比如适老化设计
信息差的来源：
-
术语
使用标准的术语
同一个意思尽量用一个词表达
提供术语解释 -
相似物
描述两个类似概念/功能时，一定要解释清楚，容易区分，避免模棱两可
-
新事物
所有新出现的事物都需要充分解释其来源。
了解读者【怎么做】
主动走近读者
-
邀请同事评审
把身边同学作为目标受众，获得反馈意见。
-
读者访谈
用户访谈，了解他们对文档的期待、建议和意见
-
文档支特群
建立文档支持群，收集第一手的文档问题。
头脑风暴自问
-
读者从那里来？
背景是什么？读者调到了什么困难，要完成什么任务？读者最开始是什么状态？他们此时在做什么，手边有那些资源？
-
读者在哪儿？
读者此时所处状态？比如，此时在那个文件夹下？读者怎么确认他们处于文档里说的这个状态？比如执行某个命令，应该返回什么结果？
-
读者到哪里去？
为什么要告诉读者这些信息？对他们有什么用？下一步要做什么？是否要提供下一步的提醒或链接？
结构化写作
学习谋篇布局，搭建清晰的文档框架，体现内容之间的联系。
文档框架：是各个部分的相互搭配方式，体现作者的思考路径
什么是结构化写作
- 理清信息之间的逻辑关系
- 把无序信息排列为有序信息
- 创造逻辑且顺畅的信息流
- 有逻辑有条理地提炼和组织内容
为什么要用结构化写作搭建框架
为作者理清写作思路
帮助作者在清晰分类的基础上全面考虑问题，找到写作的方向和重点。
为读者降低阅读成本
帮助读者快速锁定目标信息，短时间内理清文章结构，获取重点信息和核心观点。
如何结构化写作
搭建文档框架
基础：框架化思维——论，证，类，比 四原则
横向：同一层次的内容（并列或推进关系），拓宽内容广度
结构化呈现方式
- 无序列表：没有特定顺序的列表，各个列表项之间属于并列关系。
- 有序列表：强调排列顺序的列表，各个列表项之间属于先后关系。
- 表格：一种可视化交流模式，也是一种组织整理内容的手段，主要用来罗列和对比信息。
写好标题
标题：指明文档内容的概括性语句
随着内容的深入，最开始拟定的标题可能会变。所以可以先写框架和主要内容，再提炼标题。
标题的分类
总标题：文章核心内容的体现
副标题：对总标题加以补充和解说
分标题：文档内的分级标题，能清晰地显示文章的层次
好标题的重要性
可提升浏览量，更容易被引用
帮助读者快速了解文档的主要内容
如何写好标题
Simple 简明扼要：核心关键词，10字以内
Profit 利益相关：体现读者切实感兴趣的点
Accurate 准确客观：不宜过多表达主观情绪，概括文章内容即可
极简写作
用精简有力的语言来传递内容
什么是极简写作
尽可能减少读者理解信息的成本
极简写作的好处
节省时间，易于理解，减少成本
如何极简写作
保持一致
最简单，但最易忽略
如：术语，语言风格，操作描述——「体验的一致性」
避免啰嗦
简化效果最直观，需要在长期写作训练中习得
提供路标和指引
把前因、经过、结果讲清楚
有特定的故事线：引导用户掌握行文特点和要点
方式多样，如标题、导航等
检查文档
何为“检查”
对文档的体检——
写作：以创作者视角表达和呈现信息。
检查：以批判者视角审视已经写好的内容。
如何检查文档
- 先冷却，后自查
- 检查要点：主题，结构，标题，内容
