词语
-
定义专业术语。
如果已有专业术语，提供专业术语的链接。新术语需要提供定义。如果文档术语较多，需要提供附录。
-
保持一致。
使用了某个形式的术语，之后都要保持一致。比如 Protocal Buffers，如果使用了protobufs指代，即往后都需要使用 protobufs。
-
恰当使用缩写。
段落中使用了缩写，往后也要使用缩写，不要来回在全程和缩写之间来回切换。
-
何时使用缩写。
如果文档中频繁出现某个术语，或者全称极度长。
-
代词。
不中途切换代词指代。
主动语态
技术文档绝大部分情况应该尽可能使用主动语态。区分主动语态和被动语态：
主动语态：
主动语态 = 操作者(Actor) + 动作 + 目标 // 例子：猫坐在垫子上
被动语态：
被动语态 = 目标 + 动作 + 操作者(Actor) // 例子：垫子被猫坐在上面
祈使词语可以省略操作者(Actor)，比如： 『打开 package.json 文件』
使用主动语态的好处：
- 读者心智上不需要在这两者之间来回切换。
- 被动语态不直观
- 主动语态通常更简短
简明的句子
技术文档不是营销文案，尽可能减少不必要的形容词和副词。
例子：
开了这个选项让应用极其快。
改为：
开启这个选项让应用快 225-250%。
简短的句子
和编码一样，使用简短句子的文档好处是：
-
更加容易看懂
-
更加容易维护
-
更加不容易出错
-
一个句子只说一件事情
例子：1950年后期为编程语言的重要时期是因为IBM发行了Fortran和次年John McCarthy发明了Lisp，这让程序员可以以迭代或者递归来解决问题。
改进后：1950年后期是编程语言的重要时期。IBM在1957年发行了Fortran。随后次年John McCarthy发明了Lisp。所以，在1950年后期，程序员可以通过迭代或者递归来解决问题。
-
把长句转成列表
例子：更改循环体可以：
- break, 退出整个循环
- continue，停止当前迭代，继续下一个迭代
- 排除或减少冗余的词语
列表和表格
列表分为几种：
- 无序列表（Bulleted Lists）
- 有序列表（Numbered Lists）
- 行内列表（Embedded Lists）
使用无序列表，更改条目的顺序不影响整个列表的逻辑。相反，使用有序列表的时候更改顺序影响列表的逻辑。
例子：
无序列表：Bash 提供以下处理字符串的功能：
- 从字符串的开始删除子串
- 读取整个文件到一个字符串变量
有序列表：通过一下步骤重新配置服务器：
- 停止服务器
- 编辑配置文件
- 重启服务器
行内列表：列表分为无序列表、有序列表和行内列表。
总的来说，行内列表用于技术文档比较不那么地友好，尽可能把行内列表转换成有序或者无序列表。
并联列表项
列表项尽可能表达平级、相似的意思，比如：
- 胡萝卜
- 青菜
- 土豆
而不是：
- 胡萝卜
- 青菜
- 夏天的太阳
有序列表使用命令式的动词开始
- 下载 VSCode.app (https://code.visualstudio.com/download)
- 移动下载内容到 /Applications 目录下
- 打开 VSCode.app
创建可用的表格
表格在段落中暂时很容易就能获取注意力。
段落
- 开门见山
- 一个段落一个话题
- 不要太长或太短
- 包含 What ，Why 和 How
受众
好的文档 = 你的受众完成某个任务需要知道的知识技能 - 你的受众现有的知识技能
换句话说，要做到这点：
-
定义你的受众
首先确定你的受众的角色（role），比如有：
- 软件工程师
- 技术人员（非软件工程师，比如技术经理）
- 专家
- 学生
- 应届生
- 非技术职位
-
确定你的受众将学会什么
列一个清单表明受众需要要完成的目标：
阅读该文档后，你应该能做到： * 使用 Zylmon API 列举旅馆的价格 * 使用 Zylmon API 列举旅馆的地址 * 使用 Zylmon API 列举用户评分如果是编写设计文档，则列举受众将会知道的知识点：
阅读该文档后，你应该能知道： * Zylmon 打败 Zyljenue 的三个原因 * Zlymon 花费 5.25 人年工程量开发的五个原因 -
根据以上情况调整文档
- 专业词汇和概念
- 专家盲点（Curse of knowledge）- 指一旦学会了某种复杂的概念，就丧失了对别人解释这个概念的能力
[图片上传中...(image-38d119-1601351217806-0)]
总结
- 使用术语要一致
- 避免有歧义的代词
- 尽量使用主动语态，而不是被动语态
- 选择准确而不是模糊的动词
- 一句话说一件事情
- 把长句转换成列表
- 消除不必要的词语
- 顺序相关时候使用有序列表，不相关则使用无序列表
- 列表条目要对等
- 在有序列表开头使用命令式词语
- 段落开头使用中心句
- 一个段落一个话题
- 确定受众将会学到什么
- 文档为受众服务
- 在开头建立文档的中心点
网友评论