技术写作指南 - 合

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

Chapter 9 - 法律要求

到目前为止，本手册涵盖了很好的主题，但是你的手册中必须包涵一些内容。

文档应该使读者准备好安全的使用本产品。美国法律规定，手册必须列出「有意或无意但是可合理预见的产品使用方式」可能造成的任何危害。在下列情况下，你有法定义务警告消费者：

• 所提供的产品是危险的
• 危险是或者应该被制造商所知
• 产品以通常或者预期的方法使用时存在的危险
• 危险并不明显，但是对用户而言是众所周知的

未能「充分」警告消费者会让公司面临诉讼。那么，究竟是什么让一个警告「充分」？不错的问题。「充分」几乎不可定义。定义不够准确更容易。以下是手册不通用的几种常见问题：

• 未能警告用户如何正确的使用本产品
• 未能警告正确使用产品带来的风险
• 未能警告任何合理可预见的产品滥用

关键的共同点是，列出的所有内容都可能导致人身伤害或者死亡。

你的读者也必须能够看到这些安全信息。所以，警告应该从其他文件中脱颖而出，可能带有图标、彩色字体或者粗体字。它们也应该易于被读者所理解。一个令人困惑的警告与一点都不警告同样糟糕。

许多公司在手册开始时列出警告，以作为突出说明。这很好，不过也请列出读者在你的指南中可能遇到的危险。

当然，将页面和警告页作为先发制人打击诉讼的前锋确实很有诱惑力。很多公司都是这么做的。如果你自己作死把舌头和插头一起黏在插座上，那么任何电子产品对你都是一种危险。只要合理的警告。我们有时会看到各种奇怪的警告：「不要吃你的 iPod Shuffle」、「睡觉时不要使用吹风机」、「不要把冲击钻作为家庭牙科套装」等等。

在你讨论一系列不太可能但是有点微小的可能存在的警告前，我们已经警告过自己：太多的警告，尤其是荒谬的警告，会让整个靠谱的部分看起来很蠢。然后，就没有人认真对待警告——甚至真的警告都置之不理。请记住：仅当危险「合理可预见」时警告用户。参考 Goldilocks 原则找到没有足够警告和太多警告之间的平衡地带。

责任法律因国家而已。欧洲的责任法规非常严格，亚洲的责任法律也开始效仿。如果你计划再国际上销售你的产品，则必须考虑任何区域责任要求。在你发布手册之前了解责任要求和相关国际产品责任。与往常一样，向律师咨询如何编排警告的具体内容。

出版

现在，你有很多关于如何发布手册的选择。打印是其中的经典。PDF 本质上是一本以数字形式出版的数据。是现在大多数手册的默认选择。PDF 可以完成工作，但随着人们转向手机来使用手册，PDF 正在迅速变得过时。

许多手机正在通过在线发布平台来展示他们的手册。比如 wikis，就像 SecondLife 的粉丝制作的用户指南。索尼为 PlayStation 3 制作了一份定制的在线说明书，而不是标准 PDF。很多公司正在将平板电脑部署到工厂车间，用移动文档站来代替 PDF 工作指南。

现在每个人都带着智能手机，床头柜上有一台平板电脑。信息移动化——你的手册也应该这样。优化你的手册在移动设备上的表现。PDF 手册通常在手机上无法正常工作。源于纸张的传统固定宽度，它们内容太密集，难以被搜索和导航。它们在平板电脑上工作的更好，但错过了现在可能实现的大部分高级功能。

无论你选择如何发布，手册中的信息都应该很容易查阅。用户讨厌翻阅或者滚动浏览数百页来找到它们想要的一个句子。因此，如果你想要在网络上发行内容，请整合 kickbutt 搜索功能，如果你已经撰写了大量印刷手册，请编写目录和索引。

如果你需要一些灵感，请查看 iFixit 的 Android 和 iOS 原生移动应用程序。该软件是开源的，所以你甚至可以复制代码来构建自己的移动手册。

让你的手册可以在网上轻松浏览还有一个另外的关键性优势：它可以被谷歌收录。大多数用户在访问制造商网站之前会用谷歌搜索。iFixit 的用户主要通过谷歌进入——大多数人通过网页搜索来找到我们的指南。

让你的手册很容易在网上被搜索到。考虑一下潜在用户进行故障排查时可能在 Google 搜索框中键入的内容。并且在手册中使用这种语言。随着人们改变他们的搜索条件，计划再未来调整你的手册。

无障碍还意味着针对不同类型的受众进行优化。如果做得不错，盲人阅读器也很容易阅读你的手册，任何人都可以使用翻译服务以她们的母语查看网络手册。用纸质手册获得同样的可访问性是不可能的，PDF 同样很难做到。

变得更好：知识管理

发布并不是你工作的结束。文档需要不断发展。不要挣扎：你的手册会在某些时候过时——而且通常是以你从未想到的方式。

有时候，写作本身就是个错误。我们是人，写作很难。每隔一段时间，作家都会犯错误。当这种事情发生时，人们开始搞事情。没关系。任何产品的软件、硬件或者手册的 1.0 版本都不完美。

你可能会找到一个更简单的方法来处理任务，也许使用平头螺丝刀比飞利浦更容易；也许有新工具可以让事情变得简单；或者可能是流水线工人发现装配产品的一种更快捷的方式。

其他时候，产品本身也会发生变化。生产线在写完手册后进行变更：添加螺丝，重新配置磨具或者进行其他细微（或者并不太小）的更改。

规划是不可避免的。如果很难发布更改，那么你可能不会以你应该更新的节奏那样去更新文档。

如果完全有可能，我们建议你可以选择一个方便轻松更新的发布方式。不幸的是，更新纸质手册根本没用简单的方法。在 1910 年制作的「空气制动和列车信号手册」（见下图）中，作者直接在过时的信息熵粘帖更新。2012 年，丰田不得不召回数千辆汽车，只因为他们在手册中弄错了几句话。

发布 PDF 并不会给你任何灵活性。如果你已经在 1000 台笔记本电脑中发布了 1000 本 PDF 手册，则必须手动更新这些手册。没劲。如果安全关键更新漏掉了 5% 的用户会发生什么情况？这只是我们倾向于倡导中央数据存储来取代标准打印 / PDF 工作流的其中一个原因。

整合反馈

你需要你的客户——不仅仅是为了保持你的业务存在，而且还要保持你的内容蓬勃发展。你的客户能够让你变得更好。你获得的反馈越多，获得的建议越多，文档（和公司）的效果就约好。

客户可以指出文字混淆的地方；他们可以告诉你哪里的图像并没有什么卵用。招募用户帮助你改进手册。如果你提供在线版本，请为用户提供指定的问答场所，以提供反馈和编辑建议。如果你以印刷形式出版，请向读者提供他们可以联系的人以便提出问题和反馈。

API 意味着一次编写，随处发布

Google 地图安装在美国数以百万计的智能手机上。尽管 Google 不断更新和扩展它们的地图，但用户始终可以获得最新版本的地图。这怎么可能？因为人们想要的信息并未下载到他们的手机上——与此同时，每次 Google 更新地图时都不必重新下载应用程序。这些信息存在于别处，并且不断向所有连接的设备发布更新。这就是一个 API。

API 意思是应用程序编程接口：如果你在线发布，那么它可以帮助你无缝更新文档。传统上，文档更新是通过 WORD 或者 inDesign，亦或者 PDF 推送到网络、机构和归档中。如果你对 Word 中的文本进行更改，则需要对其他格式也进行更改。当每个人都有更新的副本时，又要再更新一次。使用 API 可以让你对一个中心点进行更改。然后所有更改都会立即推送到每个发布平台。

oManual 等包含 API 规范和支持移动应用的现代文档格式开始使用这项功能。

写完之后

创造你的指南只是一个开始。一旦完成初稿，就该在现场进行测试，简单修改，部署工作，聆听用户，管理未来的更新。

编辑

编辑、编辑、编辑。我们不能过分强调这个步骤的重要性。编辑组织、内容、流程和语法。你的读者得到一个打磨后的产品很重要。毕竟，当设计说明书和手册时，校对可能是福音和灾难的区别。

以下有两句话：「夏日乐趣的终极指南：烧烤小孩和家庭」和「夏日乐趣的终极指南：烧烤，孩子和家庭」。

那就对了。你和吃人之间只差一个逗号。这就是我们为什么一遍又一遍的编辑和校对。然后，当我们认为它是完美的时候，我们也邀请别人来编辑它。

大声的朗读自己的手册。如果你自己能听到，你就会发现自己的错误。

可用性测试

测试你的新说明书。请你的测试人员从头到尾按照说明进行操作。如果他们成功完成了成品而不是制造出一个怪物。那么你已经完成了作为作者的工作。一定要问你的测试人员哪些部分很难理解，为什么呢。

更新

有更新文档的计划。如果你在写一本手册，你必须承诺保持它的可靠性。每个六个月阅读一次文档以保最新。

准备好了

恭喜！我们向你致敬！欢迎来到「技术作家秘密小组」。它是个独特而微小的组织。我们甚至有一个秘密手势，一旦来到秘密会所，我们会教你的。但淡定些，那么高级。由于我们没告诉房地产经理人我们秘密会所的位置，所以目前我们没几个钱。