技术写作指南 - 承

991 阅读15分钟
原文链接: zhuanlan.zhihu.com
译者按:本书原文分为不同的 Chapter,为了方便发(cou)表(gengxin)拆分成起承转合四章,小标题按照原章节。
原书:www.dozuki.com/Tech_Writin…

Chapter 3 - 如水晶般明晰

想象一下你的话像一扇滑动玻璃门。现在脑补一下:撞向玻璃门——贼硬。这就是你的写作应该多干净:干净的要命。

避免混淆:一种常识性的方法

查看这个产品说明:

为了让来让粗略构思的机器设计理念尽善尽美,工作一直在进行着。该机器不仅能用于单边相减振器的你像反应电流,而且还能够自动同步红衣仪。这种机器就被称为涡轮机(Turbo-Encabulator)。

你 gai 到点了吗?好的,我们也没有。

涡轮机(Turbo-Encabulator)完全构成了。不过,当涡轮机的描述出现在 1946 年的时代周刊中出现的时候,大部分人都认为它是真的。为啥呢?因为他们之前看过其他不好的手册和产品说明。涡轮机(Turbo-Encabulator)是对技术写作的一种模仿,和所有的模仿一样,它太搞笑了,因为它基于现实。

另一方面,这是 100% 真实的:

延迟旋钮主扫水平方向,并且模仿机械制动,会在 0.00s 秒暂停。网格顶部是一个实心的三角符号和一个空心的三角符号。该符号表示触发点,并随着延迟时间旋钮一起移动。该符号表示时间参考点,也是放大/缩小的参考点。

当然,这个示波器操作手册不是为新手设计的。不过作者不必要的提到了「机械制动」,并且引用了一个没什么卵用的被动句。这使得句子变的难以理解。

那么,你如何避免让你的读者感到困惑?请记住,真人将会阅读你的文章,而且他们可能并不像你一样在技术领域拥有这样的知识。这里有几个建议可以让你的写作更加人性化:

使用朴实的语言:你知道吗?使用朴实的语言是一种运动。朴实的语言「关注读者」。它确保读者可以「快速轻松的发现他们想要的东西,了解他们需要的东西,并根据这种理解采取恰当的行动」。使用简单的英语, 大多数人能理解的单词和间断的语句。

简单可以引人注目。我们在阅读 William Zinsser 的写作时写道:「林肯第二次就职演讲中的 701 个单词中,这本身就是一种经济奇迹。505 个是一个音节的词,122 个是两个音节的词。」

放下行话:或者至少尽可能的使用它。行话只有在特定的学科中使用。不过,没有行业之外的人知道这意味着什么。如果你一定需要行话,尽量提供上下文,简短的定义,甚至术语表。有的时候,行话只会让你显得更蠢。例如:

额外升降运输控制杆
将小件物品放在烤面包机的顶部附近,方便拆卸。

额外升降运输控制杠杆?你说……为了方便烤面包拆卸?对你来说可能挺好……但是我们这些人只称它为「控制杆」。

不要把动词转换成名词:动词很高兴成为动词。当它们不想成为名词时,不要强迫它们成为名词。动词转换的名词让你的句子不愉快,反过来让你的读者不高兴。

下面是一些关于汽车装配线完全不可分离的工作说明:

控制杆(手柄)完全压下:
用于让发动机离合器完全脱离变速器;平稳换挡意味着正确调整离合器电缆。

现在,我们不确定标点符号到底经历了什么——我们可能永远整理不出来正确的标点使用形式,但是这些动词的名词化我们还是可以纠正的。我们要这么做:

完全脱离变速箱的发动机。正确调整离合器电缆以实现平稳换挡。

冠词不是敌人:冠词是那些名词前的小词,比如这个(the),一个(an & a)。在编写指南时,人们倾向于完全忽略冠词。他们会说:「断开电源线与墙壁的连接」(Disconnect cord from wall),而不是「断开这个电源线与其墙壁的链接」(Disconnect the cord from the wall)。我们还没有把这种遗漏的原因找出来,不过我们推测可能是因为这种机械的辞令更像是根植于内心的呐喊一般。直到奇点打击,请自由的在需要的位置使用冠词吧。

将其转交给新手:当你的写作不够清晰时,有时一件事情可能很难表述清楚。想确定你是否表达清楚了吗?把你的作品交给一个对这个主题毫不知情的新手吧。尝试一下走廊可用性测试(Hallway Usability Test):把你正在做的事情交给五个只是碰巧经过走廊的人。每当有人说:「我不知道这啥意思」的时候,就代表你已经偏离了行进的轨道。

iFixit 把原版服务手册交给了毫无准备的艺术系学生来进行测试:我们给了他们一台计算机和我们的新手册,并看着他们使用手册来把它们拆开。每当他们遇到了困难,我们就知道我们的手册有些问题。我们从他们的尝试中学到了如果去改良我们的手册。

不要使用模棱两可的单词:有些单词会把你句子中的魅力偷走。「稍微」、「看起来」、「有点」、「很」、「一丢丢」就是这些坑爹的词。它们想你的读这表明,你的意思是……你所说的,并不是那么靠谱。螺丝「很难拧紧」还是「难以拧紧」?是碰到你的前任「相当不舒服」还是「彻头彻尾的不舒服」,说出你想表达的意思,而不是模棱两可。

Chapter 4 - 写出自己的风格

手册并不是通俗小说,但这并不意味着它们不得不称为助眠神器。说明很重要,人们确实需要他们。作为作者,我们的任务是不让阅读手册让人觉得这么痛苦。写出你自己的风格!

风格并不等同一诗意的语言和强烈的意象。每个作家,不管技术如何,都有属于自己的风格。风格是你作为作者与读者的交流方式。风格包括语气、幽默、以及你的写作形式。良好的风格有益于做出抉择——知道应该包括什么、应该省略什么,何时遵守规则、何时出其不意。

你可以打破我们所列出的所有规则,不过你应该有一个明确的理由。例如,在第二章,我们告诉你要单刀直入,但是有时候,解释一个功能最好的方法是讲一个故事。在某些特定的场合下,打破这个规则也很好。讲故事的好处超过了单刀直入的好处。但不要再没有充分理由的情况下绕开规则。

允许不正经编写——但这种不正经程度应该根据主题而有所不同。如果你正在为核电厂维护程序书写手册,最好是坚持正式的,类似商业的语气。如果你正在编写如何建立后院烧烤的说明,请随意以友好和不正经的方式书写。

Mackie 的用户指南就是一个给你的灵感。Mackie 的风格是对话式的。他们了解他们的听众——专业的音响工程师,以及如何让他们 gai 到点。他们像朋友一样与读者对话,同时仍然传递详细的指南和专家级的知识。

这里有一些 Mackie 风格的亮点:

幽默的指南:
为自己打包一顿丰富的午餐,然后去外面散个步。野餐、躺下、做梦。世界如此美妙。
现实主义
仔细看这个图标会引导你对功能和实用技巧做出一些解释。如果你要匆匆离开房间,请跳过这些步骤。
讲个故事
两用静音/调换 3-4 开关是 Mackie 的代表作。当 Greg 设计我们的第一个产品时,他不得不为每一个通道都配备一个静音开关。静音开关的功能正如他们的名字那样。他们通过「遗忘」信号来关闭信号。『哎,太浪费钱了!』他感叹道,『为什么不能让静音按钮将信号路由到有用的地方,比如单独的立体声总线?』
因此,两用静音/调换 3-4 开关提供了两种功能—— 静音(通常在混音或现场演出时使用)和信号路由(用于多轨和现场工作),作为额外的立体声总线。

想要发展你自己的独特风格?下面是一些注意事项

幽默:每个人都喜欢幽默。然而应用时,你需要格外小心。幽默和机智不可能在翻译中传神,所以只有当你在为母语读者写作时才能用到它们。毕竟,美国的笑话在冰岛、土库曼斯坦或者日本可能并不好笑。另外,幽默很难有度。它需要反复推敲。甚至有时候并不合适——不要再预防措施和任何可能产生法律后果的情况下使用幽默。另外,讽刺在你自己听来可能有趣,但对于大部分人,这只是尖酸刻薄。

尽管存在一些缺点,幽默有时候是最让人难忘的方式,你自可以谈论电容器直到你脸色发青,不过他们更会记住开怀大笑的一刻。

以下是一些关于如何写的幽默的提示:

  • 只在让你发笑时写下来
  • 消除有趣的部分,并且写得更好
  • 不要强行搞笑。只有当它本身是搞笑的时候,它的效果最好。
  • 不要影射他人。你唯一能开玩笑的人是你自己。
  • 在写作前读一些滑稽的东西。我们非常推荐一个有趣的新闻记者:Dave Barry

幽默主义者 Sherman Alexie 建议:「直率的表述——这会引起你发笑」。不要在办公室尝试,它有趣依旧,但你很可能被解雇。

设定语气:你的写作可以是严肃的、权威的、新闻式的、友善的、幽默的,或者任何你想要的形式。作为一名作家,你要设定一个语气。但是不要在文档的中途改变。找到一种形式并且坚持下去。

解读观众:一个经典写作难题:作家在提到读者时可以说「你」吗?有时候,人们应该避免用第二人称来产生距离感和公平感——尤其是在科学方面的主题。但如果你告诉读者该做什么,那么「你」或者「你的」是完全可以接受的。事实上,如果是有目的的使用,非正式的「你」听着更加自然和鼓舞人心。

例:「如何将图像上传到电脑」与「上传图像到电脑」
例:「从连接器上拔出导线时要小心」与「应该小心的从连接器上拔出导线」。

当然,最终选择取决于你。

使用缩略语:使用缩略语还是不使用缩略语,这是个问题。我们有个微小的答案:「使用他们更高贵。缩略语可以缩短你的句子,改善整体的流程。」如果你怀疑这一点,请尝试朗读一段没有缩略语的句子。这听起来太烦人类了。在缩略语和段落之间来回更显得像人能看的。

简短的段落是关键:在科技写作中,格式良好的五句段落被搁置了。你并不需要在你的手册中使用这种技巧或者主题句。同事,你也不需要利用长段落来进行断言。

当你开始一个新的想法时,你可以开始一个新段落(看看我们这里是怎么做的)读者喜欢短段落。简短更容易浏览。我们喜欢用简短的、声明式的子弹把内容分成一块块小的易于阅读的结构。

国际化:如果你计划向国际读者发布,那么你需要翻译你的手册,这是一个成本极高的过程。正确的风格将会让翻译的过程变得更容易。一般的风格要点是这样的:把你的词汇量限制在简单 / 常用的词汇中更为重要。但是当你在写作翻译中,避免使用笑话和成渝(他们翻译不好),适度的使用缩略语,并与你的措辞保持一致。例如,本教程将很难翻译成另一种语言,我们使用了很多口语和成渝,以及一些比喻句。而且我们并没有打算限制我们的词汇量。这是我们为了保证这个(长篇)教程提供的信息和参与感而做出的决定。这些事作为作家必须做出的取舍。

填充一本图书有足够的国际化差异,请查看The Content Wrangler

注意事项:如果你打算将手册翻译成其他语言,那么使用大量的缩略语可能会增加你的工作成本。

Chapter 5 - 读者

写作永远不会发生在真空中(除非你真的在真空中,这就让人觉得难以置信的不爽了)当你在写手册时,你总是在为别人而写的。找出那个人是谁。你对他们了解的越多,你写的就越好。

优化你的手册以符合目标群体的专业知识。例如:傻瓜系列丛书已经瞄准了一个小的用户群:一无所知的新手。对于砂管出版社有一本关于从写简历到教育儿童的书。每一个功能都附上插图、扩展解释、上下文和基本提示。

写给傻瓜的汽车修复中有一整章致力于改变你的汽车机油。它涵盖了汽车中的油含量,合成油的优缺点和说明——整整 15 页!然而,如果这本书的标题是汽车修理专家,那么整个章节可以归结为一句话:「换油」。除非他们要给超级跑车换油,否则汽车专家不需要 15 页来指导换油。

了解你的读者意味着指导要包括什么和不不包括什么。这意味着你要向他们解释一些事情需要多少步骤。这意味着你知道你的手册要多少篇幅,以及你可以用哪几种语言。

这里有几件需要你铭记于心的事情:

阅读水平 = 写作水平

你不应该高估你的读者,也不低估你的读者,尽管低估在我们的经历中很少见。

Flesh-Kincaid 可读性测试是确定文本可读性的最常见的方法。Flesch-Kincaid 以 0-100 来打分阅读的难易度,100 为最容易阅读的。另一个 Flesch-Kincaid 测试是用于评估阅读等级的(K - 12)。

普通美国成年人的阅读水平大概在九年级。

为了向你说明多少的手册会忽视这个问题。我们决定使用 Flesch-Kincaid 标准来测试一款热门的产品:苹果 Macbook Pro 的制造商手册。苹果的用户手册评分为 2.2,阅读等级为 24(可能你会想:不,成绩不会这么高!)。作为参照,莎士比亚的 麦克白 是 11 年级的阅读水平

有一个较为靠谱的经验法则:用户手册不应该比莎士比亚难读。

iFixit 的针对同一设备的维修手册大概在 4 年级的阅读水平。阅读水平打分阅读,你的读者就越可能理解你在说什么。

不确定如何衡量你的写作水平?你可以使用「可读性测试工具」等网站来衡量现有网站的可读性。Word 和 Excel 已经 内置了可读性工具,你只要启用他们就行啦。

已有的知识

假设你的读者已经知道了一些知识?技术作家经常会忘记他的读者知道些什么,尤其是,他们不知道什么。机械工程师有时候会编写听起来像是为其他机械工程师编写的手册——但是如果目标群众不是超级精通技术的人,那么在没有解释的情况下去讨论「剪切载荷」、「螺旋齿轮传动」和「运动链」就成了一个问题。

军事组织在这方面做得尤其糟糕。他们有这么多的缩略语,所以与任何人沟通之前,你必须要花几个月时间学习所有的缩略语。以下是一个陆军舰载操作手册的例子:

a. 紧急培训。即将部署的所需的紧急需求或培训通常将会在 MACOM(比如 FORSCOM)从 DA 处获得。陆军航空兵部队将在调度船舶和其他资源方面获得更高级的指挥协助。

技术协作的标准做法是在第一次使用时明确缩写,将首字母缩写放在括号内。这确保了让读者一目了然。