技术写作指南 - 转

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

拍摄过程

有人曾经说过……一图胜千言。一点不错！不要只告诉读者怎么做，向它们展示一下怎么做。

纵观历史，图在手册上并没有得到足够多的关注——甚至是在服务手册上，照片大概是不太好的刹车与停下来的汽车之间的区别。标准化的圣杯，ISO 9001 文件通常只有文字。鉴于历史上印刷成本的高昂，这确实有一定道理。但是过去是过去，现在是现在。欢迎来到数字革命：世界成为了你的高分辨率的囊中之物。

iFixit 教人们怎么去修理他们的电器。这确实是一笔很冒险的生意。毕竟，在任何设备中都有大量的小部件和微小的连接器。以零插入力（ZIF）连接器为例，它们不仅更小，而且还配备有更小巧，更细腻的襟翼，必须撬开来并整个翻转过来。用错误的方法来做可能会破坏整个设备，不过这却是新手技术人员常犯的错误。这的确有相当的风险。

下面是 iFixit 的文本说明。用于拆卸 iPod Nano 中的 ZIF 电池连接器：

用手指按住浅色插座。然后使用撬棒的尖端将 ZIF 电线锁向上翻转 90°。

虽然这是很好的指南，但这样还不够，有太多错误的空间了。所以，iFixit 的每一步都包含高分辨率的彩色照片。这样，你可以放大并精确计算组件的外观，翻盖的位置以及撬动它的方法。像这样的照片拯救了许多 ZIP 连接器的生命：

照片带来生活中的指南。它让事情变得更清晰。将宜家手册和 iFixit 的自我修复指南相比较，根据清晰程度的不同，修理你的 iPhone 可能比组装一套橱柜更加容易。

摄影技巧

不是摄影专家？别担心！现代相机使得拍摄有用的照片变的非常简单快速。我们的技巧和教程让你在瞬间专业摄像。下面的每个链接都有来自 Dozuki 的关于产品摄影的详细步骤指南。

设置照片拍摄

拍摄照片最重要的组成部分是选择正确的相机。我们强烈建议你使用数码单反相机（DSLR）拍摄专业品质的指导图像。如果你没有 DSLR 相机，任何至少有 600 万像素的傻瓜相机将可以拍摄足够分辨率的图像。

我们公司（Dozuki）帮助公司创造服务手册，工业工作指南等的分布流程。

无论您决定使用哪种相机，每个手持相机都容易产生抖动和震动，从而导致图片模糊。使用三脚架，即使最便宜的那种，也能保证你的图像够清晰。

你的灯光越好，你的后期越少。不幸的是，你的旧床头灯并不会减少这个流程。别绝望！你可以使用简单的灯具，合适的灯泡与干净的白色表面可以构建一个相对便宜的 DIY 摄影工作室。

如果你想投资专业照明设备，适当的照相灯具应装有三个火四个独立的灯泡。为了减少刺眼的眩光，请在每个固定装置的前部装上散光片。

拍摄完美的照片

光圈和 ISO：了解光圈和 ISO 将帮助你拍摄专业的照片。光圈设置改变了透过镜头的光亮，人们通常称其为「f-stop」。ISO 设置以牺牲图像颗粒感为代价来改变相机传感器的灵敏度。我们在教程中详细的解释了这两个问题，因此在您开始编写手续之前，请不断地练习、练习、练习，方法就是拍照。

快门速度：只要按下快门按钮就可能会导致相机震动，产生的模糊的图像。模糊是不可接受的。使用远程快门释放工具，计算机共享软件，比如 Nikon Capture，Canon Digital Photo Professional 或者 Soforbild（我们最喜欢的工具）。如果无法连接，请使用相机的自拍器以防设备碰撞。大多数较新的相机都有一个很好用的 2 秒定时器，就是用在这个地方的。

构图：在为手册拍照时，将所做的所有事情都放在框架的中心，并从用户的角度来观察。

特写：放大以获取特定动作的详细镜头，特别是在执行更小或者更复杂的任务时。不过要注意，在超缩放镜头之外中间视图会让观众不丢失上下文。

使用双手

如果你正在编写说明，我们建议你尽可能的在图片中出现双手。双手非常擅长展示每一步中描述的操作。与没有包含双手的图片不同，这些图片与实际执行的用户真正想做的任务相关联。用户手册中包含了处理复杂组件的首部特写，可以让用户更好地了解如何复现所需的操作。

iFixit 手册已经培训了数以百万计的新手电子维修工程师，通过使用循序渐进的带手部特写的高分辨率彩色照片展示该过程，看着这些图片，用户可以轻松的自行重复相同的过程。

专家提示：
不要用手遮掩动作。有时这意味着拿一件物品或者工具的方法和平常不同。它可能让人感到尴尬，但由此产生的图像会更清晰的表达你的动作。第二张图比第一张图更有效的展示了打结的方法。

处理你的照片

程序：很少有完美的图片，需要一些编辑处理才能使其被用于手册。有许多照片编辑程序，比如 Photoshop（要钱）和 Gimp（免费）可以使用，学习一个软件开始编辑你的照片。

颜色和曝光：编辑时，调整光照水平以适当的平衡拜仁和黑人。调整色调和饱和度以纠正背景中的颜色错误。

编辑：并非所有的工作环境都非常干净，因此拍摄对象可能会受到头发、灰尘、污垢或者其他不完美之处的影响。如果可能，用一丢丢编辑魔法来去除瑕疵。

标记：在使用摄影作品时，我们建议使用标记来突出显示照片的某些区域。如下面的示例（Dozuki 已经有一个内置的标记系统）。多色框和源泉非常适合突出你想要读者关注的区域。下面的标记颜色已经被选中，以便色彩辨识障碍人士可以区分。

使用其他视觉效果

当你想要解释某个作品是如何工作的、如何组装或者修复的时，视频、插图、图解和图表能够发挥意料不到的效果。更棒的是，视觉效果能让文章更简洁。

图表和插图

图表和插图是为读者提供设备、部件、组件的大图片布局的好方法。你包含的视觉内容越多，你必须使用的词语就越少。它们还擅长攻克难以察觉的隐藏元素，例如汽车的接线示意图。

仅当图像可以支持、替换、增加文本时才应该使用。

下面是一个来自 Mackie Onyx 模拟调音台的示意图，这是一台带有大量连接线，差头和装饰的极其复杂的机器。这个不错的图表能够清楚的显示这些插头的功能：

Mackie 的图表很棒。不过根据我们的经验，糟糕的图表远比好的多得多。大多数情况下，图表都不够完整，缺乏足够的描述。还有一些效果不好，太凌乱，或者没有足够的书面解释。想象一下，图标看起来像这样，试图把许多东西放在一起：

或者，这样怎么样？

当你处于复杂的维修或者安装工作中，错误的图表不会有任何帮助。

视频说明

人们喜欢的不仅仅是一张图片，人们更喜欢一张张动态的图片。如果你以电子刊物的形式发布，则可以直接将视频嵌入手册中，听上去很棒吧？

http://ifixit-guide-objects.s3.amazonaws.com/igo/video/ifixit/ofb4HQVGqgNuKSRk_MP4_592.mp4

人们被视频教程所吸引。它们复刻了我们刚开始学习时最希望的一对一，专家对学生的关系。视频教程非常流行，以至于 YouTube 已经成为了互联网中电脑维修、设备配置到物理等方面的权威。在 YouTube 视频中搜索「如何操作」已经获得了超过 1900 万的点击量。关于如何在两秒内折叠 T 恤的单个 YouTube 教程已经被查看了数百万次了。

视频教程可以让学习变得更容易，但是——一个大警告——他们也容易过度使用或者让人混乱。如果你视频的读者正在查找特定的信息，视频可能会让人心灰意冷。当他们只对定位螺丝感兴趣时，没有人想要观看 20 分钟的视频。

将视频作为文档的主要来源之前，请权衡你的选择。大多数情况下，单张照片或者好的图标在识别连接器、部件和过程方面更有用。而且，与视频不同，图片可以一眼就被看到。建议只有在其他视觉效果无法表述时才使用视频。

如果你想要将手册国际化，避免在图表中使用文字或者在照片中叠加文字——否则，您需要为每个地区制作不同版本的图片。

在以下情况下使用视频

• 演示旋转步骤，比如如何打开一个不太好用的阀门。
• 演示涉及到的行为，比如为缝纫机穿针引线，撬锁或者打结。
• 演示不能通过图片或者文字进行描述的状态，比如测试你制作的蛋挞是否「足够松软」，确定引擎正在发出哪种叮当声，或者确定你搅拌的混凝土是否足够厚。
• 演示使用多大的力量，比如在实际弹出之前，你需要多大的力气才能拉动 iMac 的盖子。

如果你已经决定采用视频指南，那么在编辑室里运用这些规则。视频指南应该简洁、明确、清晰。

我们拍摄了很多独立的视频教程，但我们发现使用视频最好的方法是将他们之间嵌入到在线的逐步的指南中。简短的视频剪辑与图表、照片和文本在一起能发挥非常好的效果，以增强你的教程的可读性。

视频教程频繁出现的问题

问题：在本地化过程中，翻译音频需要额外的工作。

解决方案：视频教程中没有口语。

问题：更新视频来配合新版比更新照片和文本更不方便，成本更高

解决方案：明智的使用视频，避免可能无法用于未来的视频。并将原始视频文件保留在版本控制系统中。

问题：扫视特定信息的视频比扫视文本和照片更慢。

解决方案：缩短视频长度并提供具有针对性的具体信息。

问题：你无法搜索视频所涵盖的信息。

解决方案：给视频加上字母并且让文本可搜索，或者复制文本中的信息。

问题：手册有时需要打印。即使使用黑白打印，照片也可以平稳降级，但是视频信息会完全丢失。

解决方案：使用其他视觉效果，除非视频是必须的。那么就选择一个有用的缩略图图像。

以下是我们的经验法则：录像不应当超过 30 秒。有时 3 秒视频足以说明问题。视频越短越好。

图标和符号

任何专业的第一条规则都是不要受到伤害（尤其是因为伤害会让公司面临诉讼，正如我们在第九章讨论的那样）。因此，尽最大努力不要让人们处于着火或触电的危险之下。

如可能造成伤害，请说实话。但是这是一个难题：大多数读者阅读时，你需要的并不仅仅是大字报般的吸引读者的注意力。这就是图标和符号派上用处的地方。

一些手册，比如 For Dummies 系列，读者需要记住 12 个不同的图标。没有人会在他们的脑海中记住这个多符号。只有少数人会做危险操作时，不要使用一大堆符号。我们建议至少使用「注意」「小心」和「警告」作为安全标志。并非所有的图标都需要翻译。请务必使用普遍接受的图标，比如 splat 符号 或者 ISO 或 ANSI 发布的图标。

借助 Dozuki，你可以将警告符号集成到必要的步骤中。即使没有 Dozuki，你也不必盲目。国际标准化组织（ISO）有一套标准的国际警告和安全标志，而美国国家标准学会（ANSI）则公布美国的安全标准。如果你将国际出版，请咨询两个组织的标准。

Chapter 8 - 组织你的内容

没有单一正确的标准答案来组织你的手册。你创建的手册应该反映你正在撰写的任何产品或者流程。以下是我们遇到的组织难题中的一些常识解决方案。

大纲到永远

大纲是写作中必要的部分。大纲就像一个路线图。他们给了你的写作大方向，告诉你你该去往何方。没有大纲的工作就像试图从加州到纽约那般，你只知道该一路向东。

让自己置身于观众的位置

尝试从目标受众的角度想象事物。预测你的读者可能有疑问的地方，或者他们如何可以快速达成目标。以此来进行组织。

以任务为导向

人们阅读手册是因为他们想要搞懂一些事情。按照「快速开始」、「故障排除」、「更换点火开关」、「使用武士剑来防御僵尸」等活动来组织你的手册正文——无论你认为读者可能有兴趣完成那些任务。

使用列表

人们喜欢列表。在互联网上，名单几乎和猫一样流行。不幸的是，我们还没有找到适合的方式让非兽医将猫集成到技术文档中（噢，我们已经尝试过了）。但是，列表是一个导向。无论是编号还是符号，简短的列表都易于理解，具有高可读性。

不确定哪些章节或者小节适合你的手册？互联网上有很多现成的模板，调用它们，不过抵制完全借用它们的冲动。用其设计你自己的结构。看看其他类似流派的手册。找出你喜欢和不喜欢的点，用这些信息来改造你的手册。

编写有用的指南

我们多年来一直在尝试编写说明手册。我们所学到的最惨痛的经验教训之一是，伟大的手册不会一蹴而就，他们不得不经过反复的实验和改写。

有时候，读者会在意想不到的地方失败。我们要解释这一点很困难。在 PowerBook G4 上，光驱连接器非常难以看清。我们作家很难解释如何在不破坏连接器的情况下关闭驱动器。当我们在网上发布指南时，有人用了指南并成功破坏了他的电脑。

在我们的郑重道歉后，我们重写了指南。一次又一次。直到他达到完美，以下是重写的最终版：

我们在那次经历中学到了一些东西。现在，我们不等到人们损毁了他的东西再来重写。我们将立即征求用户的反馈意见。当我们发布 XBox 和 PS3 的修理包时，我们征求购买者的反馈。然后我们用他们的反馈来重写指南，我们还在指南中整合了评论功能，以便读者可以分享他们遇到的麻烦并且说出他们是如何克服的。

找到一些方法来获得你的指南的反馈。你不需要一个网站来做到这一点。处于负面反馈的接收端是你做的最艰难的一件事情——但他也是你写作中不可或缺的部分。如果有必要的话，贿赂一下朋友和同事，跪求他们的反馈。饼干、酒精或者是帮他们打杂——无论用什么办法。

公开这些反馈意见可能会让你的手册达到非常惊喜的高效。我们的读者告诉我们，iFixit 手册的评论通常与手册本身一样有用。

组织

编写指南的好处是它们已与组织。按照他们需要完成的顺序去编排。我们发现，使用高分辨率的图片、图表和视频进行逐步说明是设计指南最有效的方式。如果你使用视觉效果进行大部分的说明，那么大量段落就变得不再必要。

说到指南，一些准备工作可以防止让读者变的沮丧。以下是开始工作之前告诉读者的一些好消息：

• 难度级别：新手应该了解程序的难度。
• 所需时间：没有人喜欢弄清楚要花 4 小时才能完成的一项任务，这要花掉他们 4 小时。特别是如果他们本需要在 30 分钟前完成。确保预计的时间考虑了任何先决条件所涉及的时间。如果你是一名专家，并且正在为新手读者写作，那么假设他们会花费 20-50% 的时间来执行相同的任务。考虑你时间估计中的差异。
• 所需材料：如果需要工具，部件和材料，请提前列出它们。

智能的内容复用

当你为单个设备或者机器（或者类似的设备）编写大量的手册时，复用内容可以节省一大堆时间、工作和空间。

复杂的任务需要很多依赖程序。例如，无论你是在更换汽车上的刹车片还是旋转轮胎，这两项任务都需要先取下轮胎。我们喜欢称之为相关任务。比如，取下轮胎这个条件——因为你在完成整个任务前必须先完成这个步骤。

复用作为先决条件的步骤，而不是在每次出现时重写它们。大部分出版手册将先决条件指南放在同一个地方，并要求读者在各个部分之间来回翻阅。所以先决条件被列为一个步骤：

• 第一步：把你的右脚放进去。
• 第二步：取下轮子，见先决条件中的 3/4。
• 第三步：将右脚伸出来。

完成先决条件的步骤后，你会回到原来的指南并转到第三步——就想一本错综复杂的「选择你自己的冒险」书。在不同部分之间来回翻转并不方便，但是这是在纸上你可以做的选择中最好的。然而，在电脑上，你可以做的更好。

不要像对待印刷手册那样对待电脑中的手册。这样做对更先进的技术施加了不必要的限制。不要要求读者通过不同的网页来回查看先决条件。而是直接将先决条件指南集成到教程中。这样，你的读者需要的所有说明都在一个网页上。

例如，下面是一个用于移除 Macbook 电池的 iFixit 指南。电池拆卸指南是同一台计算机的 RAM 替换指南的先决条件。你可以看到，MacBook RAM 指南的前两步实际上是取出电池的步骤。Dozuki 软件不需要我们的用户像在印刷书记中那样在各个章节中来回翻阅，而是让我们在同一页面上列出所有步骤，以实现无缝的用户体验。

许多发布平台允许你智能复用内容，将某些过程标记为需要它们的指南中的先决条件，并自动插入于指南。