技术写作指南 - 起

这篇指南将会将你如何创建从手册到工作指南的任何内容。我们将帮你避免所有最常见的技术写作陷阱——从不良计划到过时出版。

译者按：本书原文分为不同的 Chapter，为了方便发(cou)表(gengxin)拆分成起承转合四章，小标题按照原章节。
原书：https://www.dozuki.com/Tech_Writing

Chapter 0 - 欢迎光临

所以，你决定写一本手册。我们衷心祝贺你在这里带领你自己 DIY。欢迎来到技术交流的世界！

现在，在这个时刻，你可以能会对自己轻笑：“技术交流？……这不是一个矛盾吗？”

我们懂了！不好的手册有过很多……Emmmm一言难尽。有一种普遍的体验：你拿出了小朋友的圣诞礼物，然后打开了组装手册，突然间，一切都变得可怕了起来，有什么地方错了错了！三个小时后，你费尽心机想要展示的是一个突变三轮车。小朋友会不高兴。

学习一些东西最好的方法是让一位专家来教你，不过手册是第二好的。一本很棒的手册，比如 iFixit 或者 Mackie 的手册，都是一位位老师。

我们推测你来这里的原因是——你想编写一本实际教导人们如何做事的手册。

我们需要帮助。该计划将教你如何撰写操作手册，工作指南以及服务手册——从计划到写作到出版，我们还将帮助你避免技术写作中最常见的缺陷。

手册很重要，无论您是在写关于如何对数控机床执行维护工作、使用视频编辑软件、烘焙鸡蛋奶酥、还是重新构建浏览器，你都是在教别人一些新的东西。如果你的手册成功了，读者将会做到一些在没有你的帮助下没法做到的事情。这真是非常 Amazing！

Chapter 1 - 在你写作之前先看看

卓有成效的写作是一项成就。现在的说明并不仅仅应该是一个有用的方向清单。他们应该拥抱这个时代的审美和惯例：高度可视化、时尚化、互动性和精心设计。当它们都被精巧的设计完毕时，这将会是一条通往优秀的途径。

现在，你可能醉心于写作。但是，在你开始奔向技术写作的夕阳之前，请记住：大部分手册和指南都是由没有第一手知识的人撰写的。我们认为者存在一个问题。编写一个好的手册需要的不仅仅是写作技巧，同时也需要理解。和技术写作有两条法则：

• 了解产品和过程
• 与专家交谈

了解产品和过程

技术写作的第一要求是知识，在你自己学会之前，你不能教别人怎么做。如何你正在编写汇编指南，请将产品放在一起。如何你正在写关于软件的内容，请使用这个程序。如果你正在编写一本产品的手册，你应该知道产品的内部和外部。使用它，把它拆分开，弄清楚它的工作原理和它这么做的意图。

一旦你认为你已经了解了这个过程，就试着交给别人。教学是巩固自己知识的一个很好的方法，并且通过观察你的学生的努力消化你所教授的内容会让你的手册变得更好。

和专家交谈

如何你不是你将写作内容这方面的专家，那么和别人交谈是个不错的选择。与开发人员、技术人员或者设计人员聊天。让他们给你一个产品、过程或者软件的演示。询问他们是如何创造的，为什么是怎么做的。然后，如果你需要帮助，记得不断的求助。

尽可能的多收集他们的故事，了解整个创造过程会帮你梳理你的理解。

通常如何编写手册

通常如何编写手册：技术编写者会根据原始功能的规格创建初稿。当然，真正的产品往往不符合最初制订的初稿，初稿完全是在浪费时间。作为令人沮丧的审查过程的一部分，工程师给作家潦草的手写笔记。技术作家编写另一份草稿，不过工程师又很快把它给撕了。这过程又一次重新开始。最后，文档终于发布了。

但它不一定这么绝对。工程师与作家之间的互动越频繁，最终的产品就会越好。

Chapter 2 - 简洁

样式提示 #1：单刀直入，一招毙命。然后停止写作。

如何你正在为了互联网写作，那么这条规则就适用了。出于某些原因，Chrome / Safari / Firefox 都被称为 Web 浏览器，而不是 Web 阅读器。人们不会阅读网站，他们只会匆匆过目，去寻找他们认为相关的单词和短语，普通人在一个网页上只会花上几秒的时间，只能阅读 20% 的文字。你写的越简洁，读者实际获取到的信息就越多。

从传统的角度来看，甚至纸质手册也不是「精读」的。没有人在晚上用手册卷起自己。像在网页上一样，人们只会寻找他们想要的信息。手册中信息越密集，人们就约难以挖掘到其中有用的信息。

比如说，看看这个厨房设备的保修声明，真实的故事：

示例1：我们建议您及时填写并寄回随附的产品注册卡，以便我们确认您的原始购买日期。但是，产品注册卡的寄回并不能减免消费者保留原始购买证明以获得保修权利的需要。如果（In event that）您没有购买日期的证明，则此产品的购买日期将为生产日期。

看着只有三句话，但它太啰嗦烦人了，一点都不人性化，下面是我们的修改：

示例2：请寄回填完的产品注册卡，以便我们确认您的购买时间，保留购买的原始凭证以确保您的保修权利。如果（If）您不知道购买时间，请改为生产时间。

这不更棒吗？

如何让段落更简洁

提炼重要的信息：将有用的信息前置。假设你的读者们不会在阅读整个段落中打嗝，当你从重要的信息开始时，你的读者将把重点放在这些信息身上——即使他们没有阅读完全文。

抛弃不重要的信息：读者只需要事实，所以删除任何离题的信息。消除额外的噪音，如果你在教我们如何重建汽车引擎，那么我们不需要听任何野马的历史。只要给我们说明就好。

检查你的字数：示例 1 有 76 个字，我们修改之后有 37 个字。言简意赅是一个伟大的目标！

专业提示：简洁，尽可能的减少单词而不改变含义

如何让句子更简洁

短句是你的朋友：自作聪明的作家长长喜欢用非常、非常、非常、非常长的句子。专业提示：真的不要这么做！太长的句子让人困惑。努力让句子不超过 24 个字。是的，我们知道——有时候你的产品名都会比这个长。不过，尽你所能，你的段落会因为健康的句子长度而变得更好。

这是一段来自反铲手册的长句：

将小型90°适配器接头组装到过滤器底座的出口端口并定向，使接头的自由端指向反向铲，并从水平向上成约30°角。

现在，这是我们用三句短句替换一个长句的版本：

将小型90°适配器接头连接到过滤器基座的端口。 配件的自由端应指向反铲。 将配件角度向上水平约30°。

删掉任何空洞的单词：空洞的单词就在那里——像长卷木中的一个包。回顾一下保修的范例，反铲机手册使用了如果（In the event of），其实就是 If 的同义词，但我们为什么要把一个词就能说通的话用四个字来表述。

减少被动语态的数量：被动语态整天闲着刷存在感，然而并没有做多少实事。当然，不要过分追求而把你的每一个被动语态都删掉。有些句子要求使用被动语态——绝对不能替代它。但是，在你有选择的地方，使用一些主动语态来代替被动语态——将句子中的动词向前移动。有一个有趣的事实：本段不包含任何被动语态。

这里有一个汽车装配手册的例子：「如果你损坏了任何零件，可能是因为它们没有被妥善的保存好，或者使用了错误的工具来安装它们」。

这里同一句话中有三个被动动词，我们删修订了新版来修正：「不正确的存放工具或者使用错误的安装工具可能会导致部件的损坏」。

战略性的使用被动语态：不管你的英语老师在十年级时说过什么，使用被动语态都不会让你成为一个坏人。记得有目的的使用被动语态。除非你有不得不使用被动语态的理由，否则请切换成主动语态。

以下是用户手册中被动语态的示例：「加高座椅应该被用于适当安装的安全带」。

谁安装的安全带？是谁在使用？这就是被动语态的问题：没人知道。句子的结构并不是《推理女神探》中的一集。没有人应该去猜测是谁做了什么。如果正在书写大方向，请以动词开头。

让我们尝试用主动语态重写：「使用加高座椅来正确安装儿童安全带」。