熟练为用户编写技术文档的提示。
第一部分
在上一篇文章中，我们概述了对
产品进行
文档记录和本地化的过程。
这次，这是
我们技术作家Andrei Starovoitov的手册
，它将使您的文档更易于用户理解（Apple，Microsoft和其他公司使用所描述的技术来记录其产品）。
众所周知，好的文件记录并不是奢侈的事情，而是增加公司销售额的一种手段。 如果您要开始或已经在开发某种程序，那么要进入该市场，您需要一个用户手册（也称为用户指南）或至少一个文档，该文档告诉客户如何开始使用您的产品（所谓的入门）。
您可以决定用哪种语言编写文档（俄语，然后翻译，或者立即用英语）。 在Parallels，我们选择了第二种方法。 用英语进行描述通常要容易得多，因为几乎所有（现在可以说“所有”）俄语的计算机术语都是借来的。
在本文的后续部分，我们将重点介绍俄语和英语示例。
那么编写文档时应该寻找什么呢？
文档中的主题类型
撰写主题时，首先需要确定主题类型：)
从这将取决于什么以及如何在其中编写。
主题主要有
4种 ：
•
描述如何解决特定任务或几个相关任务的主题（英文中，此类型的主题称为
任务页面） 。
例如，“安装Parallels Desktop”或“关闭或暂停Windows”。 这些主题中的每个主题都描述了用户为了实现特定目标而必须采取的一系列一个或多个步骤。 用户手册主要包括此类主题。
通常，用户不喜欢阅读，尤其是在文本很多的情况下。 因此，您应该尝试使这些主题尽可能简短。 理想情况下，如果信息以以下形式表示：“您可以做一些事情，只需单击此处和此处”（任务主题将在本文的下一部分中进行详细讨论）。
如果开发人员认为用户需要了解任何其他信息，并且其中有很多，那么最好在概念性主题中进行描述（请参见下文）。
•
概念主题 （英语-
概念页 ）。 在这些主题中，没有有关如何解决任何问题的说明。 它们包含的信息反而有助于更好地理解事物。 例如，概念性主题用于：
-向用户确切说明任何流程的工作方式；
-告诉您可以在应用程序设置中做什么；
-描述产品新版本中的新增功能；
-提供其他信息，以帮助用户更好地理解或解决问题。
请注意，必须在概念性主题中准确提供其他信息（如果有很多信息的话），以免使任务主题超载。
•
帮助主题 （英语-
参考页 ）-包含用户可以定期参考的信息，以了解特定术语的含义，功能的工作方式等。 此类指南的一个很好的例子是指南末尾的字典（又名词汇表）。 参考主题对于解释各种界面元素的目的特别有用。
•
描述如何解决问题的主题 （英语-
故障排除页面 ）。
例如：“我无法激活Parallels Desktop”或“我无法连接到Internet”。 这些主题描述解决问题需要做什么。 它们可能还包含有助于理解故障原因的信息。
所有类型文档的基本说明
创建指南时：
1）
专注于用户
•与其根据功能或界面元素来构造产品说明，不如将精力集中在用户最有可能尝试解决的任务上。
例如，关于如何在虚拟机中保护数据的主题可以称为2种方式：
a）“安全设置”，详细描述了可以采取哪些措施保护数据。
b）制作几个描述特定任务的主题：
-“使用防病毒软件保护您的数据”
-“备份您的虚拟机”（“备份您的虚拟机”）
根据当前的文档趋势，第二种方法是可取的，因为在这种情况下，用户不必猜测是否要做某事，并且他会收到明确的指示以明确需要做什么。
•关注用户的任务及其技术素养水平。
例如，在普通用户的文档中，您无需编写“创建虚拟机”，而应编写“安装Windows或任何其他操作系统”，如“ “虚拟机”并不是所有人都知道的。 或另一个示例-描述如何创建快速键盘快捷键的主题，最好调用“配置键盘快捷键”而不是“键盘设置”。
尽管这很重要，但对于大多数Habr读者来说，“配置快捷方式”会更清楚，但问题是，目前在官方术语中该术语多少合适：）
•如果不清楚，请解释为什么用户可能需要执行特定任务。
例如：
•描述时，请尝试使用用户每天在演讲中使用的单词。 如果技术上比较复杂的术语可以用更简单的单词代替，请始终尝试使用更简单的单词。
例如，“透明”而不是“透明”。 如果您使用英语提供示例，请使用“使用”而不是“利用”。
2）
尽量提供所有必要的信息，不要多余的文字“来自萨摩斯岛的大使来到斯巴达寻求帮助。 他们发表了漫长而优美的演讲。 斯巴达人说：“听完结尾，我们忘记了起点，忘记了起点，我们不了解终点。” 萨摩兹人机灵。 第二天，他们拿着一个空袋子来到会议上，只说了四个字：“有一个袋子，没有面粉。” 斯巴达人责骂他们-两个词就足够了：“没有面粉”，但他们对如此机灵的机智感到满意，并答应提供帮助。如果您对功能的描述时间过长，那么没人会阅读。 但这也完全是“斯巴达人”的方式，因为如果写得太少，就会有疑问和疑问，用户将开始寻求支持团队的支持。 通常，保持平衡很重要。
为了帮助用户找到所需的所有信息，同时尽可能简短地描述每个部分：
- 专注于解决该主题中描述的问题所需的最重要信息。 如果该任务不需要一些细节，请不要描述它们。
- 无需记录每次点击。 如果界面中的所有内容都清楚，让用户自己弄清楚。 例如，最好不要编写文档来记录程序安装的每个步骤：“要安装程序，请按照屏幕上的说明进行操作。” 如果作为过程的最后一步，您必须单击“确定”，那么这也不值得描述。
- 与其在一个主题中提供所有信息，不如向用户显示您可以使用其他主题的链接，外部资源的链接或在末尾插入“相关信息”部分（其中包含以下内容的链接）来阅读其他信息：与屏幕上描述的内容相关的主题。
- 如果可以将一个长任务分为几个阶段或子任务，每个阶段或子任务都是一个单独的任务，则将该主题分为相应的部分，或在指南中创建一个由描述每个阶段的主题组成的部分。 在这种情况下，请不要忘记插入指向相关主题的链接。
- 如果可以通过多种方式执行任务（例如，启动虚拟机），则无需全部描述它们。 提及最快和最简单的方法就足够了。 如果您仍然认为对于用户了解任何其他方法很有用，请在最后（英语-Outro）主题中对其进行描述。
3）
不要在页面上重复相同的信息
与其重复在其他主题中已经描述的每个主题中的信息，不如说可以在此类主题中找到更详细的描述，或者只是给它一个超链接。
4）
正确吸引用户的注意
当描述需要引起用户的注意时，使用以下介绍词-“注意！ （英语-警告！），“重要：”（英语-重要：）和“注释：”（英语-注意：）。
这些词中的每一个都暗示着自己的“重要性”水平。
为了不使用户徒劳，请正确使用每个术语：
- 注意！ （警告！英文）表示危险情况，如果不避免，可能会导致数据丢失，组件损坏或任何其他损坏。
- 使用“重要提示：” （英语-重要提示：）表示严重且可能存在问题的情况，但是这种情况不会导致物理损坏，损坏或数据丢失。
- 使用“注意：” （注意：）来提供与此主题相关的任何其他信息。 尽管这样的插入会使用户脱离当前任务，但它可能会很有用。
例如：
要打开虚拟机配置，请单击操作>配置。
注意：必须关闭虚拟机。
请谨慎使用“注：”注释-如果插入过多，将阻塞文本，并且不再引起注意。
如果可能，请在主题的开头插入“注意！”，“重要：”和“注意：”，以便用户在开始执行任何步骤之前先了解一下。 但是，如果信息仅涉及特定步骤，请在此步骤之后插入。
一个例子：
待续...（在本文的下一部分中，我们将更详细地讨论描述如何解决特定问题的主题）