笔记：
- 本章以及本技术写作教材的其余部分，专注于 技术写作技能此处的技术内容不保证成功、准确或最新。
- 请点击这里以提供帮助 大卫·麦克默里 支付网页托管费：请捐款您能提供的任何金额！在线技术写作将保持免费。
本章的重点是技术写作中最重要的用途之一—说明书。如您所知， 指示 它们是逐步说明如何做某件事情：如何构建、操作、修理或维护东西。
编写工作或技术写作课程的说明书？试试这个。 指导说明规划指南.
写作说明
技术写作最常见也是最重要的用途之一就是说明—这些逐步解释如何做某事的内容：组装某物、操作某物、修理某物或进行某物的例行维护。但对于看似如此简单和直观的内容，说明文却是你能找到的一些写得最糟糕的文件。像我一样，你可能也经历过许多由于说明书写得糟糕而令人恼怒的经历。本章接下来将不是一份万无一失、不出错的说明书写作指南，但它会向你展示专业人士认为的最佳技巧。
最终，良好的指导写作需要：
- 清晰、简洁的写作
- 对整个过程及其所有技术细节的透彻理解
- 您将自己置于读者的位置的能力，即试图使用您指示的人的能力。
- 你将手术过程详细可视化并将这种意识记录在纸上的能力
- 最后，你愿意付出额外的努力，测试你为其写下指令的人。
到现在为止，您可能已经研究过标题、列表和特别通知。用这些工具编写一组说明可能看起来很简单。只需将讨论分成编号的垂直列表，并在明显的地方添加一些特别通知，您就完成了！嗯，其实还不完全是这样，但这是一个很好的开始。本章将探讨说明书的一些特性，这些特性可以使它们变得更加复杂。您可以利用这些考虑来规划自己的说明。
NotebookLM生成的本章节信息图
一些初步准备
在写说明书的项目开始时，确定您要写的特定程序的结构或特征是很重要的。
观众和情况。 在过程的早期，明确你的指令的受众和情境。记住，定义受众意味着要定义他们对主题的熟悉程度以及其他相关细节。请参见讨论的内容。 观众 以及用于定义受众的步骤。
最重要的是，如果你正在上写作课，你需要写一份关于你的受众的描述，并将其附在你的说明上。这将使你的导师能够评估你的说明是否适合预期的受众。还要记住，在技术写作课程中，为非专业受众写作是更可取的—这对你作为写作者来说是一个更大的挑战。
任务数量。 您所写的程序中有多少个任务？我们用术语。 程序 以指代您指示要讨论的整个活动集。 A 任务 是在整个操作微波炉程序中，一个半独立的行动组：例如，设置微波炉的时钟是操作微波炉这个大程序中的一项任务。
一个简单的程序，如更换汽车的机油，仅包含一个任务；没有半独立的活动组。一个更复杂的程序，如使用微波炉，包含许多这样的半独立任务：设置时钟；设置功率级别；使用定时器；清洁和维护微波炉等等。 使用相机的说明 按任务组织。)
一些指令只有一个单一的任务，但在这个单一任务中有很多步骤。例如，想象一下为儿童秋千架组装的一组指令。在我的经验中，步骤超过了130步！这可能会让人感到有些压倒。一个好的方法是将相似和相关的步骤分组为不同的阶段，并在每个新阶段重新编号步骤。 相位 然后是单一任务程序内的一组相似步骤。在秋千架的例子中，搭建框架是一个阶段；将其固定在地面是另一个阶段；组装箱式秋千又是另一个阶段。
使用任务导向。专注于您的读者想要执行的任务；在标题中使用“如何”或“–”的表述。
逐步讨论的最佳方法。 另一个考虑因素，也许你无法早期确定的，是如何集中你的指导。对于大多数指导，你可以集中于任务，或者你可以集中于工具（或工具的功能）。
在一个 任务方法 （也称为任务导向）对于使用电话接听服务的说明，您会有以下几个部分：
- 录制您的问候语
- 播放您的消息
- 保存您的消息
- 转发您的消息
- 删除您的消息等
这些是—我们希望与机器一起完成的典型任务。有关进一步讨论，请参见章节。 任务分析.
另一方面，在一个 工具方法 关于使用复印机的说明中，将会有这些不太可能的部分：
- 复制按钮
- 取消按钮
- 放大/缩小按钮
- 装订/钉书按钮
- 复制大小按钮等。
如果你为这个计划设计了一套指示，你会为使用复印机的每个按钮或功能编写步骤。使用这种工具的方法很难奏效。有时，按钮的名称与其关联的任务不完全匹配；有时你必须使用不止一个按钮才能完成任务。不过，有时工具/功能的方法可能更可取。
任务分组。 列出任务可能不是你需要做的全部。可能有很多任务，你必须将它们分组，以便读者能更容易找到单独的任务。例如，以下是说明中常见的任务分组：
- unpacking and setup tasks 拆包和设置任务
- 安装和自定义任务
- 基本操作任务
- 例行维护任务
- 故障排除任务；等等
说明中的常见部分
以下是对您常在说明中找到的部分的评估。不要假设它们每一个都包含在内。 必须 实际写的指示中不必包含这些内容，也不必以这里呈现的顺序排列，也不意味着这些是指示集中唯一可能的部分。
当你阅读以下关于说明书中常见部分的内容时，请注意 示例说明.
指令的示意图。 请记住，这是一种典型或常见的内容和组织模型，还有许多其他可能性。
介绍。 仔细规划您的指示的介绍。确保它执行以下任何操作（但不一定按此顺序），适用于您的特定指示：
- 指明要解释的具体任务或程序，以及涵盖的范围（什么） 不会 被覆盖）。
- 指明观众在知识和背景方面需要什么，以理解这些指示。
- 给出程序的大致过程和它所完成的工作。
- 指明这些指示应该（或不应该）使用的条件。
- 给出说明书内容的概述。
查看此部分关于 介绍 以便进一步讨论。
一般警告、注意、危险通知。 说明通常必须提醒读者有可能损坏他们的设备、搞砸程序和伤害自己。此外，说明还必须强调关键点或例外情况。对于这些情况，您使用 特别通知—注释、警告、注意和危险通知。请注意上述示例说明中如何使用这些特殊通知。
技术背景或理论。 在某些类型的说明开始时（当然是在引言之后），您可能需要讨论与该过程相关的背景。对于某些说明，这个背景是关键的—否则，过程中的步骤就没有意义。例如，您可能有过使用那些软件小程序的经验，在其中您通过调整红色、绿色和蓝色滑块来定义自己的颜色。要真正理解您在做什么，您需要对颜色有一些背景知识。同样，您可以想象，对于某些使用相机的说明，也可能需要一些理论。
设备和用品。 请注意，大多数说明包含在开始程序之前需要收集的物品清单。这包括 设备，您在过程中使用的工具（例如搅拌碗、勺子、面包烤盘、锤子、电钻和锯子）以及 供应品，在过程中消耗的物品（例如木材、油漆、油、面粉和钉子）。在说明中，这些通常以简单的纵向列表或双列列表的形式列出。如果需要为某些或所有物品添加一些规格—例如品牌名称、尺寸、数量、类型、型号等，请使用双列列表。
步骤讨论。 当你真正开始写步骤时，需要考虑几个方面：(1) 步骤的结构和格式，(2) 可能需要的补充信息，以及 (3) 视角和一般写作风格。
结构和格式。 通常，我们想象一组指令是以垂直编号列表的形式格式化的。实际上，大多数都是这样。通常，您以这种方式格式化您的实际逐步说明。然而，也有一些变体以及其他一些考虑事项：
- 固定顺序步骤 必须按照呈现的顺序进行的步骤。例如，如果您要更换汽车的机油，排放机油就是一个步骤。 必须 在加新油之前。这些是编号列表（通常是垂直编号列表）。
- 变量顺序步骤 可以按照几乎任何顺序执行的步骤。 很好的例子是那些故障排除指南，它们告诉你检查这个、检查那个，当你试图修复某个问题时。 你可以以几乎任何顺序进行这些步骤。 对于这种类型，项目符号列表是合适的格式。
- 交替步骤 是在提供两种或更多实现同一目标的方法的情况下。备用步骤也在可能存在各种条件时使用。使用带有项目符号的列表，并在选项之间插入“或”，或使用引导词指示即将呈现替代方案。
- 嵌套步骤. 在某些情况下，程序中的单个步骤本身可能相当复杂，需要拆分为子步骤。在这种情况下，您需要进一步缩进并按顺序标记子步骤为 a、b、c 等等。
- "无级" 说明书. 最后，确实存在一些指令无法使用编号的垂直列表，并且几乎不对读者进行任何简单的指导。有些情况必须是如此普遍或变化多端，以至于无法陈述步骤。
请参见这一章关于 列表 对于这些可能性的风格和格式。
补充讨论。 通常，仅仅告诉读者做这个或那个是不够的。他们需要额外的解释信息，如在步骤之前和之后事物应该是什么样子；他们为什么应该关心这一步骤；在他们所做的事情背后是什么机械原理；甚至更微观层面的步骤解释—对构成该步骤的具体动作的讨论。
补充讨论的问题在于，它可能隐藏了实际步骤。你希望实际步骤—读者要采取的具体行动—突出显现。你不想让它全部淹没在堆砌的文字中。至少有两种方法可以避免这个问题：你可以将指令与补充信息分成单独的段落；或者你可以加粗指令。
在说明中加粗实际用户步骤。 粗体文本有助于区分实际操作和补充信息。
避免电报式写作—省略理解的冠词（the, a, an）。确实，机器人是那样写的，但我们不必这样。
写作风格。 你实际上写指令的方式，句子一句接一句，可能与以前的写作课程教你的内容相矛盾。然而，请注意，"现实世界"中的指令是如何写的—它们使用了很多命令句（指令或直接称呼式的写作）；它们大量使用"你。" 这是完全合适的。你希望引起读者的注意，让她或他完全专注。因此，指令风格的句子听起来像这样："现在，按下前面板上的暂停按钮以暂时停止显示"以及"你应该小心不要..."
一个特定的问题涉及说明中的被动语态使用。出于某种奇怪的原因，一些说明听起来像这样："暂停按钮应该被按下以暂时停止显示。"我们不仅担心暂停按钮的心理健康，还想知道谁应该按这个按钮（你是在对我说话吗？）。再看看这个例子："定时器按钮随后设置为3:00。"同样，作为遵循这些说明的人，你可能会错过这一点；你可能会认为这只是对某种现有状态的参考，或者你可能会想，"他们是在对我说话吗？"几乎同样糟糕的是使用第三人称："用户应该按下暂停按钮。"同样，这是让人错愕的旧问题：你环顾四周，想，"我吗？"（有关更多细节，见 被动语态问题.)
另一种常见的写作风格问题是在说明中人们似乎想要省略冠词："按下前面板上的暂停按钮以暂时停止信息显示"或 "地球人，请提供最近比萨餐厅的地址。"我们为什么要这样做？我们都秘密地想成为机器人吗？无论如何，请确保包含所有冠词（a, 一个, 这）和我们通常在指示中使用的其他这样的词。
说明中的图形
可能比其他任何形式的写作（也许除了漫画书）更重要，图形在说明中的作用至关重要。有时，文字无法解释某个步骤。插图往往对读者能够想象他们应该做什么至关重要。
在技术写作课程中，指示可能要求您包含插图或其他类型的图形—无论在指示中通常使用什么。问题当然可能是您无法访问适合您特定指示的图形，并且您对自己的艺术能力没有特别自信。解决这些问题的方法是存在的！请查看 里的建议。 图形在那一章中，您不仅会看到创建图形的建议，还会看到它们格式的要求。
格式在说明中
标题。 在你的说明中，合理使用标题。通常，你会为任何背景部分使用标题，为设备和用品部分使用标题，为实际说明部分使用一般标题，以及为该部分内的各个任务或阶段使用子标题。查看本章开头的示例。 标题 用于常见需求。
列表。 类似地，说明通常大量使用列表，特别是用于实际逐步解释的编号垂直列表。简单的垂直列表或双列列表通常适用于设备和材料部分。在句内列出清单在你概述即将到来的内容时是很好的。见 列表 对于常见的需求。
特别通知。 在说明中，您必须提醒读者可能会损坏设备、浪费材料、导致整个过程失败、伤害自己或他人—甚至导致严重或致命的后果。公司因缺乏这些特别通知、特别通知写得不当或特别通知不合时宜而被起诉。请参见 特别通知 有关这些特殊通知的正确使用，以及它们在说明中的格式和位置的完整讨论。
数字、缩略语和符号。 说明中也使用了很多数字、缩写和符号。对于 指导方针 在这些领域。
说明中的通知缩进。 在第一个例子中，请注意通知是缩进到 文本 在前一步骤中。在第二个示例中，请注意严重通知被放置在任何步骤之前。
AI 指令提示
检查清单通常很少被阅读，但经过一些修改可以作为AI提示的来源。复制以下内容，将其粘贴到如Google的Gemini等AI系统中，看看您可能错过了什么。
注意：所有关于内容、格式、指令风格或其组件的参考信息均可以在其中找到。 在线技术写作教科书.
当你想使用人工智能来评估一个写作项目时，先介绍自己，告诉人工智能你是谁，你想要什么。给人工智能一个评估的参考点，比如在线教材。然后发布你希望人工智能检查的内容以进行评估。
修改介绍以符合您的身份。
|
AI 提示说明 你好，AI。我请求你评估一位美国大学二年级学生写的指示。以下是教科书章节的摘要。 指示 和 通知 作为您评估的基础。（识别信息已屏蔽）：
|
相关信息
阅读测验使用此测验来测试你对本章的理解。
如何编写说明书. 技术撰写
我会很感激你对这一章的想法、反应和批评： 你的回复—大卫·麦默里.
