技术写作指南 - 合

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

Chapter 9 - 法律要求

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

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

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

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

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

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

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

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

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

15204859039705.png

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

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

15204859101943.png

出版

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

15204914733546.png

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

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

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

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

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

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

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

变得更好:知识管理

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

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

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

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

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

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

15204921775359.png

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

整合反馈

15204923776687.png

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

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

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

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

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

15204925841304.png

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

写完之后

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

编辑

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

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

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

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

可用性测试

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

更新

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

准备好了

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

15204935158780.png

如果您觉得文章不错,可以通过赞助支持我

标签: 知识, 写作

添加新评论