技术写作须知
该译文对应原文: Notes on Technical Writing
再过去的一年,我断断续续为 WordPress 文档工作。在冻结发布期间,我开始为开发者迁移到新平台做出贡献。我发现自己很享受写文档,同时写文档也有益于帮助和指导他人。虽然这不是我的主要工作,我还是会抽出时间保持贡献。
这段时间,我阅读了大量关于技术写作的资料。这是我的笔记,不仅帮助我后续记忆,也可作为我目前写作的参考工具。
原则
以下原则是撰写文档时须谨记的
- 技术写作的目的是更快更好的帮助用户完成任务
- 实践出真知,演示优于描述
- 让用户尽快获得成功
译者注: 技术写作必须尽早让用户获得反馈和价值
- 文档类型不是只有一种
译者注: 要根据目的选择技术文档的类型
建议
- 明确你的受众和写作意图
- 重要的信息放在前面
- 善用列表
译者注:例如编写技术教程,采用有序列表编排示例步骤,便于读者操作和定位问题。
- 一个段落,一个概念
- 勤于修改
避免元写作
避免写描述写作的内容,文字本身没有思想,是笔者和读者赋予了文字灵魂。
你不需要告知读者接下来要说什么,直接说就好了。
- 反例: 本章节讨论影响名气起伏的因素
- 范例: 名气起伏受什么影响?
不要在写作中引用章节
- 反例: 总结上一章关于......
- 范例: 综上所述.....
不要描述极度复杂的概念,同样也不要讲显而易见的内容。读者会自行判断概念的难易。
极简教学
John M. Carroll 和他在 IBM 的同事研究如何创建支持文档,分析使用户熟练掌握的最佳方案。在 1980 年代，他们开发了一种极简方法，并编写了一本极佳的《IBM Displaywriter 操作员培训手册》，提供给首次使用文本处理器的人。
译者注: Displaywriter 是 IBM 开发的电子文档编辑器
极简教学的四条原则:
- 选择面向行动的方法,用户总期望做点什么。这条原则反映了极简主义以用户为中心的本质。
- 明确任务域的工具。工具是达到目的的手段。该原则要求设计人员选择对用户有意义的培训任务。
- 提供错误识别和恢复,人非圣贤,孰能无过,提升用户处理错误的体验和能力。
- 明确准备,学习,定位。设计必须尽可能满足目标受众的不同需求和倾向。该原则也反映了极简主义的以用户为中心的本质。
深入阅读极简教学出自荷兰特文特大学的教学技术系。
建构主义
美国心理学家 Jerome Bruner 研究人类认知心理学。布鲁纳著作的一个主要议题是确认学习是一个主动的过程，学习者基于已有的知识构建新的概念。将建构主义原理应用于文档：
- 鼓励读者去发现原理
- 将信息转换为读者当前可以接受的水平
- 以递进方式编排材料,在已掌握知识上构筑新的概念
- 融入活动对话框,鼓励用户去操作 “试一下”,"看看发生了什么","自行验证"
进一步阅读 Bruner 构建理论
文档类型
Daniele Procida 撰写了关于文档你不知道的 不是所有的东西都叫文档，这里(至少) 有四种类型文档。
- 教程(Tutorials) 教程面向教学针对初学者,通过一系列指导课程,给用户提供基本的信心和技能。教程不应该预设知识或语言,但是任可帮助那些一无所知的初学者。
- 使用指南 使用指南或者 FAQ 是面向目标的。由用户确定,使用指南可以假定用户具有预设知识和语言，但是需要知道如何解决特定问题。
- 说明 说明或概述文档是面向理解的，提供背景或额外详细的上下文
译者注: 这类似文档概念建立和术语阐述章节,例如 webpack concept
- 参考指南 参考指南是面向信息的，它应该准确而完整的描述机理。API 文档是参考指南的典型事例。