技术文档写作

1. 思想的组织

1.1 金字塔原理

  • 结论先行：一篇文章只支持一个中心思想，这个中心思想将概括各级各组的所有观点，必须放在文章最开头。
  • 以上统下： 上一层级的观点必须是对下一层级观点的概括，下一层级的观点是对上一层级观点的解释、支持。
  • 归类分组：把具有共同点的观点归类分组，同一组中的观点都必须属于同一个范畴。
  • 逻辑递进：每组中的观点都必须按照逻辑顺序进行组织。

1.2 序言

1.2.1 SQAC

  • S:背景 介绍读者熟悉的某些“背景”
  • Q:疑问 由此引发读者最初的“疑问”
  • A:回答 针对该“疑问”给出的“答案”，也就是文章的中心思想
  • C:冲突 说明发生的“冲突”

1.2.2 TOPS

  • Target to Audiences 有的放矢 内容面向读者，抓住读者的注意力
  • Overarching 贯穿整体 能够全面概括后面的内容
  • Powerful 掷地有声 有见解
  • Supportable 言之有据 有论点可以支撑

1.3 自上而下构建

  1. 提出中心思想
  2. 设想读者最初提问
  3. 写序言
  4. 与读者进行疑问、回答式对话

1.4 自下而上构建

  1. 列出想表达的所有观点
  2. 找出各观点之间的逻辑关系
  3. 概括总结，得出结论

1.5 归类分组

  • 相互独立（ Mutually Exclusive）：同一组的各个观点之间必须相互独立、相互排斥，没有重叠。
  • 完全穷尽（ Collectively Exhaustive ）：同一组的所有观点完全穷尽，没有遗漏。

1.6 逻辑顺序

  • 时间顺序
  • 重要性顺序
  • 结构顺序

2 语言的表达

2.1 文章的易读性

2.1.1 词汇

突出含义、简洁易懂、避免歧义，明确是否

  • 避免使用介词、连接词、转折词
  • 避免使用程度副词、情绪副词
  • 避免使用代词
  • 避免使用多音多义的词汇
  • 注意修饰词的位置
  • 避免使用相对时间
  • 注意上下文的一致性

2.1.2 句子

句子：以句号结尾，能够表达完整的意思

  • 语法准确
  • 精简语句，突出主旨

2.1.3 段落

段落：一般由多个句子构成

  • 相似信息采用列表展示
  • 多个信息含有相同属性且属性内容各不相同时，宜用表格
  • 善用图形

2.2 文章的易理解

2.2.1 举例增强理解

2.2.2 标题反映主题思想

  • 避免使用整句
  • 避免使用复杂句式
  • 标题结构一致
  • 减少冗余
  • 下级标题不能重复上级标题

2.2.3 step by step

一个步骤包含一个要执行的动作，让读者变成“傻瓜”，按部就班地执行就能轻松完成任务

DITA全称是Darwin Information Typing Architecture，中文名叫“达尔文信息类型化体系结构”，近年来在国际上的技术文档写作领域很流行，尤其是在大公司中，以DITA为基础的各种商业出版解决方案应用非常多。DITA将文档主题类型划分为概念（Concept）、任务（Task）和参考（Reference）这3种：
　　概念 　　概念主题回答“是什么”的问题，提供读者能成功操作、维护、使用一个产品或者界面所必须知道的背景信息。
　　任务 　　任务主题回答“如何做”的问题，通过Step by Step的方式描述完成一个特定任务所需的方法和步骤。 　　参考 　　参考主题用于描述产品或技术中特性结构比较一致的主题，如语法规则、消息说明及参数说明等。