备注：
- 本章，以及这本技术写作教科书的其余部分，侧重于 技术写作技能. 此处的技术内容不保证成功, 准确或是最新.
- 请点击此处以提供帮助 大卫 麦克默里 为网站托管付费: 捐赠任何您能提供的金额! 在线技术写作将继续免费.
本章的重点是技术写作所有用途中最重要的一种—说明。 正如你所知， 说明 是那些逐步说明如何做某事的解释: 如何建造、操作、修理或维护事物.
一定要去看看 示例.
正在为工作或技术写作课编写一套操作说明吗？试试这个 指令规划指南.
写作说明
技术写作最常见且最重要的用途之一是说明书—这些逐步说明如何做事的内容： 组装某物、操作某物、修理某物，或对某物进行日常维护。 但对于看似如此简单直观的东西，说明书却往往是你能找到的写得最糟糕的文档之一。 像我一样，你可能也遭遇过许多因说明写得糟糕而令人恼火的情况。 本章以下内容可能不是一份万无一失、绝对不会出错的说明写作指南，但它会向你展示专业人士认为最好的技巧。
归根结底，良好的指令写作需要：
- 清晰, 简洁的写作
- 对该程序在所有技术细节上的透彻理解
- 你将自己置于读者, 也就是试图使用你 说明的人的能力
- 你有能力将程序的过程详尽地可视化，并把这种意识记录在纸上
- 最后, 你愿意多走那一步，并在你为之撰写这些指示的人身上测试它们.
到现在为止，你可能已经学习了标题、列表和特殊提示—用这些工具编写一套说明似乎显而易见。只要把讨论分成编号的垂直列表，在显而易见的地方加入一些特殊提示，就完成了！嗯，还不完全是，但这是个很好的开始。本章探讨了说明中一些可能使其更复杂的特性。你可以反过来利用这些考量来规划自己的说明。
NotebookLM 生成的本章信息图
一些初步说明
在编写说明书的项目开始时，确定你要撰写的具体程序的结构或特征是很重要的。
受众与情境. 在流程早期，确定你指令的受众和情境。请记住，定义受众意味着要界定其对该主题的熟悉程度以及其他类似的细节。参见对此的讨论 观众 以及用于定义受众的步骤.
最重要的是，如果你在写作课程中，你需要写一份受众描述，并把它附在你的说明上。这将使你的授课教师能够根据是否适合预期受众来评估你的说明。另请记住，在技术写作课程中，最好为非专业受众写作—这对你作为写作者来说更具挑战性。
任务数量。 你正在撰写的流程中有多少个任务？ 让我们使用术语 程序 指代你指示旨在讨论的整套活动. A 任务 是程序中半独立的一组动作：例如，在微波炉上设置时钟是操作微波炉这一整个过程中的一项任务。
像给汽车更换机油这样一个简单的程序仅包含一个任务; 没有半独立的活动分组。像使用微波炉这样更复杂的程序包含许多这样的半独立任务: 设置时钟; 设置功率等级; 使用定时器; 清洁和维护微波炉, 等等. (这 相机使用说明 按任务组织.)
阶段 然后是一组在单一任务过程中的相似步骤. 在秋千架的例子中, 搭建框架会是一个阶段; 将其固定在地面上会是另一个; 组装箱式秋千又是另一个.
使用任务导向。专注于读者想要执行的任务; 在标题上使用“如何”或 –ing 的措辞。
进行逐步讨论的最佳方法。 另一个考虑因素，你也许无法在早期确定，是如何聚焦你的指令。对于大多数指令，你可以侧重于任务，或者可以侧重于工具（或工具的某些功能）。
在一个 任务方法 （也称为任务导向）关于如何使用电话应答服务的说明，你会有这些部分：
- 正在录制您的问候
- 回放你的消息
- 保存您的消息
- 转发你的消息
- 删除你的消息，等等
这些是任务—我们通常想用这台机器完成的典型事情. 有关进一步讨论, 请参阅关于 任务分析.
另一方面, 在一个 工具方法 对如何使用复印机的说明，会有这些不太可能的部分:
- 复制 按钮
- 取消按钮
- 放大/缩小 按钮
- 按套/装订 按钮
- 复制大小按钮，等等
如果你按照这个方案设计一套说明，你会为复印机的每个按钮或功能写出使用步骤。采用这种工具化的方法编写的说明很难奏效。有时，按钮的名称与它所对应的任务并不完全匹配；有时你必须使用不止一个按钮来完成该任务。尽管如此，在某些情况下，工具/功能的方法可能更可取。
任务分组。 列出任务可能并不是你需要做的全部. 可能有太多任务, 你必须将它们分组, 以便读者更容易找到各个任务. 例如, 以下是在说明中常见的任务分组:
- 开箱和设置任务
- 安装和自定义任务
- 基本操作任务
- 例行维护任务
- 故障排查任务; 等等
说明书中的常见部分
以下是对你在说明中常见部分的回顾。不要以为每一项都 必须 并不意味着它们必须出现在你实际编写的说明中, 也并不意味着它们必须按此处所示的顺序排列, 也并不意味着这些是说明集中唯一可能的部分.
在你阅读下面关于说明中常见部分的内容时，请查看 示例 说明.
指令的示意图. 记住，这是内容和组织方面的典型或常见模型—还有许多其他可能性.
引言. 仔细规划你说明的引言。确保它包含下列任何适用于你特定说明的事项（但不必按此顺序）：
- 指明要说明的具体任务或程序以及覆盖范围 (什么 不会 被覆盖).
- 说明受众需要具备哪些知识和背景才能理解这些说明。
- 大致说明该过程的步骤及其能实现的目标.
- 说明在何种情况下应（或不应）使用这些指示。
- 概述这些说明的内容。
请参阅有关 介绍 以便进一步讨论。
一般警告, 注意, 危险通知. 说明通常必须提醒读者可能会毁坏他们的设备、搞砸操作流程并伤到自己。此外，说明常常需要强调关键点或例外情况。对于这些情况，您使用 特别通知—注意, 警告, 小心, 和 危险 提示. 注意上述示例说明中这些特殊提示是如何使用的.
技术背景或理论。 在某些类型的说明的开头 (当然是在介绍之后), 你可能需要讨论
设备和用品. 请注意，大多数说明都会在你开始操作之前列出需要准备的物品清单. 这包括 设备, 您在该过程中使用的工具（例如搅拌碗、勺子、面包模具、锤子、电钻和锯子）以及 物资, 在该过程中消耗的物品 (例如木材、油漆、油、面粉和钉子). 在说明中，这些通常会列成简单的纵向列表或两栏列表. 如果需要对部分或全部项目添加一些规格说明，请使用两栏列表—例如品牌名称、尺寸、数量、类型、型号等.
关于步骤的讨论。 当你着手实际撰写这些步骤时, 有几件事要记住: (1) 这些步骤的结构和格式, (2) 可能需要的补充信息, 和 (3) 视角与总体写作风格。
结构和格式. 通常，我们想象一组说明被格式化为纵向编号列表. 而事实上大多数确实是这样. 通常，你会以这种方式来格式化你实际的逐步说明. 然而，也存在一些变体，以及其他需要考虑的事项:
- 固定顺序的步骤 是必须按所示顺序执行的步骤。 例如，如果你正在给汽车换油，放油就是一个步骤 必须 在放入新油之前出现。 这些是编号列表（通常, 垂直编号列表）。
- 可变阶数步骤 是可以几乎以任何顺序执行的步骤。 很好的例子是那些故障排除指南，它们会告诉你检查这个, 检查那个，当你试图修复某样东西时。你可以几乎以任何顺序执行这类步骤。对于这种类型, 项目符号列表是合适的格式。
- 替代步骤 是指呈现实现同一目标的两种或多种方法. 在可能存在各种情况时, 也会使用替代步骤. 对于这种类型, 请使用项目符号列表, 在备选项之间插入“或”, 或使用引导语表明即将呈现替代方案.
- 嵌套步骤. 在某些情况下, 程序中的个别步骤本身可能相当复杂, 需要将其分解为子步骤. 在这种情况下, 你应进一步缩进, 并将子步骤按 a, b, c 等顺序编号.
- "Stepless" 说明. 最后确实存在那些无法使用编号的纵向列表，并且几乎没有（如果有也很少）以直接的教学式方式来指导读者。有些情况必须如此概括或变化如此之大，以致无法陈述步骤。
参见关于 列表 对于这些可能性的风格和格式。
补充讨论。 经常，仅仅告诉读者这样做或那样做是不够的。他们需要额外的解释性信息，例如在该步骤之前和之后事物应是什么样子；他们为什么应当关心执行这一步；他们所做事情背后的机械原理是什么；甚至对该步骤的更微观层面的解释—关于构成该步骤的具体动作的讨论。
将说明中的实际用户步骤加粗. 粗体文本有助于将实际操作与补充信息区分开来。
写作风格.
被动-语态 问题.)
在说明性文字的写作风格中，另一个典型问题是人们似乎想省略冠词： "按下前面板上的暂停按钮以暂时停止信息显示" 或 "地球人，请提供最近的披萨店地址。" 为什么我们要这样做？我们是不是都暗自想成为机器人？ 无论如何，务必包含所有冠词（一个, 一个, 这) 和我们通常在指令中使用的其他类似词语.
说明中的图形
可能比其他任何写作形式（也许除了漫画书），图形对说明性文字来说更为关键。 有时，仅靠文字无法解释某个步骤。 插图常常对读者能否形象地理解应做的事情至关重要。
在技术写作课程中，说明可能要求你包含插图或其他类型的图形—任何通常会在说明中使用的东西。问题当然可能在于，你无法获得适合你具体说明的图形，而且你对自己的艺术能力并不十分自信。有办法克服这些问题！看看下面的建议 图形. 在那一章中，你不仅会看到关于创建图形的建议, 还有关于它们的格式的要求.
说明中的格式
标题. 在你的说明中，善用标题。通常，你会希望为可能有的任何背景部分设置标题，为设备与材料部分设置标题，为实际说明部分设置一个总标题，并为该部分内的各个任务或阶段设置子标题。看看本章开头的示例。参见 标题 用于常见需求.
列表。 类似地, 说明通常大量使用列表, 尤其是用于逐步说明的编号纵向列表. 简单的纵向列表或两栏列表通常适用于设备和用品部分. 在句内的列表在概述即将进行的事项时很有用. 见 列表 适用于常见需求.
特别通知. 在说明中，你必须提醒读者注意可能出现的情况，这些情况可能导致他们损坏设备、浪费耗材、使整个程序失败、伤害自己或他人—甚至造成重伤或死亡. 公司因缺乏这些特别注意事项、特别注意事项写得不当或特别注意事项位置不当而被起诉. 参见 特别通知 有关这些特别通知的正确使用以及它们在说明中的格式和位置的完整讨论.
数字、缩写和符号。 指示也使用大量数字, 缩写, 和符号. 例如 指南 在这些方面.
说明中通知的缩进。 在第一个例子中，注意那则通知是如何缩进到 文本 前一步骤的。 在第二个示例中，请注意严重通知被放置在开头，位于任何步骤之前。
用于指令的 AI 提示
清单, 通常无人阅读, 经适当修改后可以作为 AI 提示的来源. 复制以下内容, 粘贴到诸如 Google 的 Gemini 等 AI 系统中, 看看你可能遗漏了什么.
注：关于申请信或其组成部分的内容、格式、风格的所有参考资料可在 在线技术写作教科书.
当你想要使用 AI 来评估一个写作项目时, 介绍你自己, 告诉 AI 你是谁, 你想要什么. 给 AI 一个用于评估的参考点, 比如一本在线教科书. 然后发布你希望 AI 在评估中检查的内容.
修改介绍以符合你的身份。
|
AI 提示词 说明 你好，AI。我请求你评估一名美国大学二年级学生写的说明。下面是关于教科书章节的摘要 说明 和 通知 作为您评估的依据. (身份信息已被屏蔽):
|
相关信息
我会很感激你对这 一章的想法, 反应, 批评: 你的回复—大卫 麦克默里.
