熟练为用户编写技术文档的提示。
第二部分继续阅读我们的技术作家
Andrei Starovoitov的手册
，这将使您的用户文档更容易理解。
您可以在
此处阅读本文的开头，但是在
本文前面我们描述了对产品进行文档化和本地化的过程。
在这一部分中，我们将详细分析主要由用户文档组成的主题（尤其是《用户指南》），即描述如何解决特定问题的
任务主题 。
该主题中要描述多少个任务-一个或多个？任务主题可以描述一个任务-“启动Windows应用程序”（“启动Windows应用程序”），以及多个相关任务。 例如，“优化性能”主题可能包括以下部分：“自动节省磁盘空间”和“调整MacBook以获得更好的性能或节省电池”（“优化您的MacBook，以提供更长的电池寿命或更高的性能”）。
我们应该尝试根据以下原则编写任务主题：一个主题-一项任务。 的确，有一个例外-如果您有两个相反的任务，则应在一个主题中对它们进行描述。 例如，如果您需要描述如何将虚拟机切换到全屏模式以及以后如何退出虚拟机，则需要在同一主题内执行此操作。
如果您需要描述几个相关的任务，则只要描述不长，也可以在一个主题中完成。
任务主题部分任务主题包括：
- 标题
- 入门部分 （英文“ intro”）
- 短语，导致对用户确切需要做什么的描述 （英文为“ step heading”）
- 编号或从头开始的步骤 （英文为“编号或项目符号的步骤”）
- 最后一部分 （英文为“ outro”）
有时，任务主题没有包含上述所有部分，例如，不需要插入Intro或Outro。 此外，我们将在该主题的每个部分上详细介绍。
标题我们必须尝试做出这样的标题，以便用户立即理解主题中将要写的内容。
使头条新闻变得宽敞，但不要同时太长。 长标题可能无法在某些浏览器或Apple Help Viewer中完全显示。
撰写标题时，请使用命令（“执行此操作”）例如，“使用Bonjour设置打印机”。
不要在没有描述如何解决问题的主题名称中使用命令式命令。
在主题名称中使用用户友好的单词，而不要专注于界面元素。用户不想了解功能，术语，界面元素等-他需要解决自己的特定问题。 因此，以该主题的名称，尝试使用用户自己会使用的那些词。 例如，如果您将主题设置为“设置Mac以使用Windows应用程序”，则它比主题“关于虚拟机”对用户更容易理解。
尝试制定用户可能会制定的目标。 例如，代替“开始远程会话”，最好将主题命名为“开始远程控制Windows”。
如果您需要使用技术上比较复杂的术语或接口名称，则最好不要在标题中，而应在主题介绍中进行。
如果您使用英语编写文档，则标题中的单词应以大写字母开头右 ：设置Mac以使用Windows应用程序
错误 ：将Mac设置为使用Windows应用程序
（我们将在本手册的下一部分中详细讨论标题的大写）。
简介（简介）在标题之后的介绍性部分中，您应该写出用户在开始执行任务之前需要知道的内容。
序言可能包含：
- 其他一般信息：用户可以做什么。
- 动机 ：为什么用户可能需要执行一个或另一个动作。 这是一个示例性介绍部分，描述了为什么您可能需要下载和使用现成的虚拟机：
使用现成的虚拟机如果您没有时间使用必要的配置来创建新的虚拟机，则可以使用预先配置的配置下载完成的虚拟机。- 关于用户执行操作时可能对硬件，软件造成的任何损坏或数据丢失的警告。
- 关于潜在问题或困难的重要信息 ，尽管它们不会导致健康，设备损坏或数据丢失，但在执行任务期间可能会发生。
- 说明：这个或那个术语是什么意思，或者任何功能是如何工作的。
例如，如果Parallels Desktop用户希望同时使用macOS和Windows（就像是一个操作系统），那么在入门部分中，您可以讨论“一致性模式”，以便为用户准备以下术语：将在本主题中进一步使用。
- 有关其他条件的信息 ：例如，在描述如何通过Bonjour连接打印机的主题中，简介可能会通知您哪些Windows版本支持Bonjour。
- 当前任务的必要条件 ：如果在开始执行本主题中描述的任务之前，用户需要执行或检查其他操作，则应在简介部分中提及。 最好提供指向其中所描述主题的链接，以便用户可以快速查找和阅读。
不要在不需要的地方插入序言。尽管简介部分提供了其他有用的信息，但有时标题本身就可以使所有内容变得清晰。 在这种情况下，您只需要提供一个介绍性文本即可。
例如：
通过“开始”菜单启动Mac应用打开Windows“开始”菜单，然后执行以下操作之一：
- 单击所有程序> Parallels Shared Applications，然后选择所需的应用程序。
- 在搜索字段中输入应用程序的名称，然后从建议的选项中选择所需的应用程序。
序言不要太长简介太长了，惹恼了用户。 在这种情况下，用户经常跳过它，直接进入特定步骤列表。
如果简介部分太大，则需要提及主要部分，并提供指向单独的概念页面或参考页面的链接，其中所有内容均已详细描述。
有时，为了在视觉上便于在入门部分阅读较长的文本，可以使用项目符号。 例如：
在介绍中不要告诉您如何完成任务
序言不是为此。 需要做什么，在哪里以及如何做-有必要在稍后的介绍部分之后进行描述。
但是，在极少数情况下，您可能需要告诉用户完成任务所需的内容。 在下面的示例中，简介部分告诉用户他们需要完成本主题中描述的任务。
不要在介绍部分中描述任务的结果。这应该在最后一部分（
Outro ）中完成。
说明前的短语（步骤标题）
在介绍之后，您需要插入一个“介绍”短语（英语-“步骤标题”），从而使用户获得指示：要获得一个或另一个结果需要做什么。
例如，在Intro中，我们写道：“
如果您有安装盘和激活密钥，则可以使用它们在虚拟机中安装Windows。 ”
在Intro出现步骤标题后：“
要安装Windows： ”
然后自己执行以下步骤：
1）点击这里。
2）选择这个。
3）依此类推...
请注意：如果主题中没有介绍，则步骤标题是可选的。
如果主题描述了顺序步骤，则步骤标题应类似于“
要做某事：”（“要做X：”）。例如：“要切换到全屏模式：”（“要启动Windows：”）或“
要切换到全屏模式：” 。
别忘了在最后加上一个冒号如果标题使用用户友好的单词，并且您必须在说明中使用复杂的技术术语或界面元素的名称，则可以执行以下操作：在简介部分中解释该术语的含义，并且在标题中您已经在积极使用它。
例如：
1）我们为用户提供更清晰的标题：
“将Windows设置为占据整个屏幕”
2）接下来，在简介中，我们引入术语“全屏模式”。
3）之后，在步骤标题中，您已经可以使用该术语，而不必担心它对用户而言是不易理解的：
“要进入全屏：”（“要进入全屏：”）
如果主题中描述的步骤不是一系列操作，而是实现目标的几种方法，则步骤标题应如下所示：
“这里有一些方法可以做某事：” （“这里是X的方法：”）或“
为此，请执行以下一项操作：” （“要做X，请执行以下一项操作：”）。
例如，“以下是关闭Windows的方法：”）或“
要连接打印机，请执行以下操作之一： ”（“要连接打印机，请执行以下操作之一： ”）。
创建步骤标题时，需要使用那些反映任务主题中描述的任务的词。 以下是一些英语示例：
页面标题 ：从安装光盘安装Windows。
任务介绍 ：使用安装光盘安装Windows。
步骤标题 ：安装Windows。
页面标题 ：调整连贯性设置。
任务介绍 ：自定义Windows在Coherence模式下的显示方式和行为。
步骤标题：自定义连贯模式。
页面标题 ：将Windows设置为占据整个屏幕
任务清单 ：进入全屏模式。
步骤标题 ：要进入全屏模式，请执行以下任一操作：
编号的步骤
描述如何执行特定任务的所有主题均包含有关操作说明。 文本中的这些操作通常用数字编号（如果是一系列连续的步骤）或用项目符号突出显示（如果建议您根据自己的意愿选择一个列表）。
保持必要步骤的列表尽可能短。选择并描述完成操作的最简单，最快的方法。 替代方法可以在最后一部分（Outro）或另一个任务主题中描述。 如果可以通过单击一个按钮来完成所有相同的操作，则不要强迫用户阅读4个步骤的说明。
如果最简单的方法是通过工具栏执行操作，请描述此选项。 如果可以根据自己的喜好来定制工具栏，并且您对此有所怀疑，突然之间，用户对工具栏的配置与本主题中所述的配置有所不同，请描述使用默认设置完成的所有操作。 如实践所示，大多数普通用户很少更改“工厂”设置。
如果您需要在一个主题中描述几种执行操作的方法 ：
如果在本书的许多任务主题中重复执行可以以不同方式执行的特定操作（例如，通过菜单或工具栏），请选择一种方法并在每个任务主题中依次提及。
如果有一种简单而又简短的替代方法，并且您当然想谈论它，则可以在同一步骤中完成。
例如：“要打开虚拟机配置，请选择“操作”>“配置”，或单击右上角的“配置”图标。”）。
编号要顺序执行的步骤。为了不使描述夸大，也不要在单独的步骤中突出显示非常简短的说明（例如“单击确定”），可以在一个步骤中组合2个相关的操作和相关的操作，如下所示：
使用项目符号突出显示不一致的操作
有时会为用户提供几种选择方式来实现目标的方式。 在这种情况下，建议的选项会发出子弹。
例如：
如果列表中包含图形元素的名称，请以粗体突出显示它们如果用户要执行的操作列出了图形界面的许多元素（菜单项，daw等），请在新行上开始每个选项，并以粗体突出显示该元素的名称。 在以粗体标记的元素之后，加一个冒号，然后以纯文本解释说明。
如本例所示：
如果主题中的文本多次引用各种界面元素，则可能值得创建一个单独的帮助主题来描述这些元素。
如果指南中的许多主题都引用相同的元素，这将特别有用。 在这种情况下，在主题的开头，您必须提供指向参考主题的链接，在其中解释了所提到的元素。
如果稍后在文本中再次提到此元素，则不再需要为其提供链接-只需在其开头即可。 当主题中的链接很多时，这会使对所写内容的理解和理解变复杂。
最后一部分（Outro）Outro是编号步骤之后的最终信息。 尝试使最后一部分更短-使用不超过3个段落，每个段落最多包含3个句子。
使用Outro来描述这些操作的结果或后果。
结果或后果的示例可能是：•有关任何文件安装位置的信息；
•出现一条消息，要求用户采取其他措施；
•完成上述操作后，用户将需要切换的设置。
例如，有关如何使Parallels Access仅在Wi-Fi上工作的主题的最后部分说：“
如果将Parallels Access配置为仅在Wi-Fi上工作，并且当前未检测到无线网络，则会出现一条消息，询问您-您想通过3G连接吗？ ”。
在主题的最后部分，您可以描述完成任务的另一种方法。
如果可以在一个句子中描述替代方法，则可以在本主题的最后部分进行。
Outro可以提供与当前任务有关的更多信息。这样的信息可以通知用户他们在完成所描述的任务之后还能做什么。
在以下示例中，主题描述了如何在macOS Finder中从虚拟机中查找文件。 并在主题的最后部分描述了找到文件后用户还可以对文件进行哪些操作。
在Outro中，您可以描述仅某些用户需要的其他信息。例如，在有关将Windows虚拟机集成到macOS中的主题的最后部分中，您可以编写以下内容：
“如果您拥有MacBook Pro 2016或更高版本，则可以使用Touch Bar处理某些Windows应用程序”
将长任务分解为短阶段基本上，任务主题简短且适合一页。 但是，如果描述了一些复杂且很长的任务，可以将其分为阶段，阶段和过程，则值得在逻辑上分离信息并在单独的主题中描述每个阶段，以便使描述看起来更简单，更好地阅读和理解。
以下是《 Parallels Desktop用户指南》内容的示例。 屏幕快照显示一章，描述了在虚拟机中安装Windows的各种方法。 其中一种方法-如何从远程计算机导入数据-分为几个主题。
待续...
（在下一部分中，我们将更多地讨论概念和参考主题以及有助于解决问题的主题）