《技术写作手册》笔记

Source: 《Tech Writing Handbook》

技术文档

• 最好的学习是你身边有一个专家(expert)教你，其次就是一个好的说明文档。
• 现代的技术文档应该是高度视觉化(highly visual), 造型优雅(sleek), 可交互(interactive), 和设计合理(well-designed)的。
• 写一个好文档有两个必要条件
  1. 了解你介绍的产品和流程
  2. 从行业的专家那学习（如果身边有就更好）

简洁 Concise

• 直接地(Be direct)表达要点，然后停止继续写的欲望
• 浏览器，叫web browsers，是有原因的，网友都是浏览（browse), 而不是阅读(read)
• 据统计[网友平均只阅读文章20%的文本]
• 对于技术文档/文章的读者来说，他只是找到他需要的内容，而不是想从头到尾线性的阅读
• 所以如果你把100的文章压缩到20，信息的到达率可能更佳
• 几个小技巧让你的文章更简洁
  • 段落的开头用粗体强调主题：就像这样，类似以前新闻搞的写作方式
  • 删除一切离题(off-topic)的信息：比如为了显得自己更博学而加的话，反而会弄巧成拙
  • 关注字数：如果100个字的段落用30个字能传递同样的意思，那就删除另外70个
  • 不要用复杂句式：用简单句，长句造成理解的成本
  • 不要拽文(Dump any empty words)：也就是说尽量不要用文绉绉的词汇，古文，等等
  • 用客观代替主观：尽量减少使用“你如果怎样，就会怎样，不然你就怎样”这样指导般的句式，而用“怎样做会导致什么”这样的客观语态

清晰 Clarity

• 避免让读者困惑，关注没有背景知识的一般读者
• 用平白(Plain)的语言，控制自己飚术语的欲望
• 如果不得已用了术语，耐心解释文章涉及到的概念（即使你自己心知肚明）
• 写完给一个外行人看一下，看他能否看懂 [Hallway Usability Test]
• 不要写自己的揣测，比如“可能”，“应该”，“大概”，如果是这样开头的信息不如不写

风格 Style

• 幽默，技术文章如果有幽默感是加分的，但不要嘲笑别人。
• 定好基调(Set the tone)：无论你是什么风格的写作，文章内保持一致
• 使用“你”，虽然其它写作中要尽量不用第二人称，但对于技术写作中，如果是告诉别人如何做，用“你”也是合理的
• 不必辩护，技术文章不需要大段文字支撑自己的段落论点，给出段落的主题，避免过度分析和举证。

了解读者 Know Your Audience

• 写作等级和阅读等级：写作等级不要超过阅读等级，如果你的目标是高中生，那不要按大学生的预期去写作
• 前置知识：明确你希望你的读者要预先理解什么知识，即使你文章不会解释，最好也要给一些链接

一图胜千言 Use Visuals

• 文字有时是苍白的，比如对于一个安装图，所以当要大段描述一个过程、一种结构的时候，试着画图

组织内容 Organize the Content

• 写提纲，比如一级、二级标题，没有这些，如同没有地图
• 任务导向，用户关注“如何做一件事”，胜过技术细节
• 多用列表，列表更容易被理解

写完之后

• 再读一遍，检查格式，语法，错字
• 更新内容，随着时间的推移可能文中的内容已经不再适用，记得更新