通用技术写作

写作前：

了解读者：

• 为什么要了解读者：

  • 保证文档的可读性

    1. 读者能够理解文档

    2. 读者可以根据文档完成任务

  • 明确读者用户：小白用户or资深用户or运维or开发

  • 明确读者的阅读目的：了解一个概念，完成一个步骤还是查阅一个参数的显示

  • 明确读者的所需信息：根据读者的认知能力提供所需信息

• 何为了解读者

  • 不要写读者不需要的东西，针对不同的人员，要明确读者需要的是什么。不要把使用手册写出了功能清单

  • 针对不同的读者群体，要学会减小信息差，清楚作者和读者之间的认知差异，要尽量弥合读者和作者的认知差。要时刻谨记读者和作者之间的信息差的存在，可能使用我的文档的人压根不了解这些。

  • 常见的信息差来源

    1. 术语：

       • 尽量使用标准的术语

       • 同一篇文章中同一事物尽量使用同一个词

       • 要提高术语解释

    2. 相似物

       • 一个产品提供了两个相似的功能时，文档需要帮助读者辨析，方便做出选择

    3. 新事物

       • 要充分解释其来源

• 如何了解读者

  • 走进读者：了解到读者的要求，了解读者对文档的期待，建立文档支持群

  • 了解读者从哪里来，读者要完成什么任务。最开始是什么状态

  • 读者在哪，了解读者处于什么状态

  • 读者去哪，为什么要告诉读者这些信息，对他们有什么用，下一步做什么

结构化写作

学习谋篇布局，搭建清晰的文档框架，体现内容之间的联系

何为结构化写作

• 理清信息之间的逻辑关系

• 把无序信息排列为有序信息

• 创造逻辑且顺畅的信息流

• 有逻辑有条理地提炼和组织内容

为什么要结构化写作：

• 为作者理清写作思路

• 为读者降低阅读成本，帮助读者快速锁定目标信息

如何结构化写作

• 搭建文档框架

  • 纵向：（让文章有深度，形成文章地主干）

    1. 论 ：结论先行。开门见山，把核心观点或者中心思想放在文章地开头位置，让读者一目了然，高效传递信息

    2. 证： 以上统下。上层结论是概括总结，然后通过下层信息进行具体解释和说明，让文档更有理有据

  • 横向：（形成文档脉络）

    1. 类 归类分组：把关联的信息按照一定的标准进行划分归类，归为同一个逻辑范畴，在分类中让混乱的事物变得有序

    2. 比 逻辑递进：按逻辑顺序排列素材

• 填充必要信息

• 巧用结构化呈现

  • 无序列表，各项之间是

  • 有序列表，各项之间有递进关系

  • 表格

写好标题：

用好SPA原则，写出精简准确的文档标题

• 标题：指明文档内容的概括性语句

  • 总标题：文章核心内容的体现

  • 副标题：对总标题加以补充和解说

  • 分标题：文档内的分级标题，能清晰地显示文章的层次

• 原则：

  • Simple 简明扼要

  • Profit 利益相关

  • Accurate 准确客观

• 文档类型

  • 概念型：介绍某个概念，内容可以是介绍背景，原理以及优劣势等。 取名：<A概述>，《A介绍背景》等

  • 任务型：指导完成具体的任务 ：名词加动词或者动词加名词 《A工具的安装》《部署A环境》

  • 参考型：罗列参考信息，比如产品的型号参数，api参数等。 名词+名词 ，如《机器配置的要求》等

极简写作：

学习如何用精简有力的语言来传递内容

误区：不是越短越极简，字越少越好

而是：简化读者理解信息成本，用最简练的语言概括最有价值的信息

如何极简写作：

• 保持一致：最简单，最易忽略，术语风格体验一致

• 避免啰嗦：简化效果最直观，去掉口语化的表述，叙事反复

• 提供路标和索引，让用户不迷路

读者是懒惰和忙碌的

检查文档，以批判者视角审视已经写好的内容

先冷却一段时间再去审查，避免陷入自我欣赏的怪圈

• 主题：是否明确聚焦，内容是否发散，是否跑题

• 结构：是否符合结构化写作，是否遵循一定的顺序

• 标题：是否符合SPA原则

• 内容：是否简单清晰，不拖泥带水

总结：

写作前：了解读者

写作中：结构化写作，写好标题，极简写作

写作后：检擦文档