如何编写技术手册
浏览：1
巴克励步
我经常看到一些企业花了大力气做产品手册，结果用户根本不爱看——要么堆砌功能列表，要么全是开发视角的术语。其实，做好一本产品手册的核心在于：搞清楚谁在用、用来解决什么问题。Baklib 的产品手册建设方案，就是帮你把用户调研、内容结构、交互体验这些环节串起来，而不是让你从零憋一篇没人读的说明书。下面这份指南，会把写手册的前、中、后步骤拆透，你可以直接套用到自己的产品文档里。 如果你希望让客户轻松上手使
我经常看到一些企业花了大力气做产品手册，结果用户根本不爱看——要么堆砌功能列表，要么全是开发视角的术语。其实，做好一本产品手册的核心在于：搞清楚谁在用、用来解决什么问题。Baklib 的产品手册建设方案，就是帮你把用户调研、内容结构、交互体验这些环节串起来，而不是让你从零憋一篇没人读的说明书。下面这份指南，会把写手册的前、中、后步骤拆透，你可以直接套用到自己的产品文档里。
如果你希望让客户轻松上手使用你的产品，你不必完全依赖支持团队。超过 60% 的客户更偏爱自助服务工具，因此确保产品技术手册足够有用是更好的选择。
由于编写这样一份详尽的技术内容颇具挑战，我们整理了一份指南，帮助你为产品创建一份出色的手册。
我们将涵盖编写前、编写中以及编写后需要采取的步骤，确保技术手册的每个方面都打磨至完美。
💛🧡🧡客户评价：由于我们使用Baklib来管理所有内部培训知识库，因此我们将每天使用该程序（以及每天多次）。内容需要有序直观，以便我们的员工在我们扩大规模时自助检索。除了拥有强大可定制的搜索功能外，Baklib 是一个易于使用的分层组织系统，在我们交叉链接文章时非常有用。
那么，一起来看看这些步骤吧。
了解你的受众
在开始编写技术手册之前，你首先应该确定你的受众是谁。
假设你正在为你公司开发的一款消息应用编写技术手册，你可能会倾向于通过代码来展示其能力，或者写得过于简洁以使其适合工程师阅读。
然而，这会让你的用户指南对普通终端用户来说不实用，这在技术写作中是不可原谅的错误。
这就是为什么你应该确切地知道你在为谁写作。
这样做不仅有助于你选择要写的内容类型，还能帮你确定最佳的呈现方式，正如技术作家 Sam Sycamore 所建议的那样。
Sycamore 认为，有些受众对写作的 DRY 原则反应更好，而另一些受众则更喜欢在必要时重复的指令。
那么，如何确定你的受众以及采用何种写作风格呢？
我们 Baklib 在受众研究过程中有一些第一手经验，所以我们会告诉你什么对我们有效。
Baklib 是一个产品文档平台，主要被软件开发团队使用，这最初让我们假设开发者是我们内容的主要读者。
直到我们进行了一次用户调查——你可以看到下面的计划——我们才发现我们错了。
事实证明，大多数账户所有者是非技术角色，如技术作家或项目经理。
这一认识帮助我们相应地调整了我们制作的内容，无论是教学类还是营销驱动的写作。
我们现在优先考虑清晰写作，避免过度使用行业术语，正如你在我们用户指南的这段摘录中看到的那样。
如果不对我们的用户群进行分析，我们可能会冒着朝与受众需求或理解相反的方向写作的风险。
幸运的是，Google Forms、访谈和销售数据洞察的组合让我们能够创建更有用的技术内容。
所以，如果你想让你的技术手册成为有价值的资源，你应该首先确定你的受众，并牢记实际读者选择最合适的写作技巧。
定义手册的目标
现在你知道了谁会读你的手册，你应该继续问他们为什么读。
你的客户是试图解决特定问题，还是想了解产品？
无论哪种方式，定义手册的目标都能帮助你编写有用且相关的内容。
我们从一个例子开始。
当你上次购买干衣机时，它可能附带一份手册，告诉你如何使用该设备，但没有描述其优点或解释设计决策。
技术手册，无论产品是什么，通常都是为了特定目标而编写的。例如，上面的手册解释了如何安装和操作干衣机，仅此而已。
如果作者偏离了让客户能够使用产品的预期目标，文档最终会变得杂乱，因而用处不大。
因此，在编写前定义手册的目标能让你为读者提供最佳的用户体验，因为它让你满足他们的需求和期望。
如果没有明确的目标，你就无法做到这一点。
为了帮助你确定技术手册的目标，我们创建了一个包含常见手册类别、文档类型和可能目标的表格。
**技术手册类别 | 文档示例 | 可能目标**
客户支持手册 | 帮助台文章、用户说明 | 帮助客户独立使用产品和解决问题
组织支持手册 | 流程文档、员工手册 | 帮助员工高效工作
IT 支持手册 | 技术规范、需求文档 | 帮助开发团队创建软件产品
上述目标都是指令导向的，大多数技术手册也是如此。
毕竟，人们很少浏览手册，除非他们当时需要它。
鉴于客户期望手册是指令性的，考虑将任何额外信息转移到产品文档的其他部分。
一旦你确定了手册的目的，你就能确定最合适的格式来组织内容，使你在进入写作阶段时更容易。
创建大纲
现在距离编写技术手册只有一步之遥了！创建手册大纲是最后的准备步骤，对于为写作过程带来结构至关重要。
技术手册可能信息密集。如果你没有正确组织信息，你在写作时会遇到困难，用户阅读时也会挣扎。
为了防止这种情况，最好列出你要表达的主要观点，并将它们组织成标题和子标题。
你可以在 Google Developers 的软件文档大纲中看到一个很好的文档组织示例。
当然，实物产品的手册大纲会不同于侧重数字产品分步说明的手册。
尽管如此，无论产品是什么，你都可以遵循一些通用指南来创建有效的大纲。
例如，最好先确定主要部分，然后逐步细化到产品的较小部分。
这种方法的最大好处是，它同时能生成一个可搜索的目录，读者以后可以使用它来浏览手册。
在开始写作前创建大纲的另一个好处是，你还能识别出哪些信息可以省略。
正如我们所说，技术手册应帮助用户实现特定目标，任何不必要的信息都会使寻找相关说明变得更加困难。
因此，如果一条信息与你确定的大纲不符，最好将其省略，以使手册更加清晰。
有了大纲，现在该动笔编写技术手册的初稿了。
编写手册
此时，你已经通过定义技术手册的受众、目标和大纲打下了基础。
在本节中，我们将回顾一些最佳写作实践，帮助你就接下来的步骤做好准备，使内容更加有效。
让我们从用户打开手册时立即看到的内容开始。
如果你向他们展示一堵文字墙，他们将很难找到正确的信息，并可能对产品感到沮丧。
这就是为什么技术写作专家，如 Kesi Parker，建议用视觉元素丰富手册。
“说明书通常很无聊。吸引读者注意力并帮助他们理解信息的唯一方法是使用视觉元素。”
根据 Parker 的说法，视觉元素不仅使手册在视觉上更具吸引力，而且帮助用户更好地理解和记住信息。
例如，如果你在写分步说明，用截图补充步骤可能会很有帮助。
同样，你可以通过包含产品零件的技术插图或组装所用的工具来提高实物产品技术手册的质量。
不过，当简洁的文字说明就足够时，你不应过多地用图片填充文档——手册的目标是提供信息，内容杂乱可能会阻碍其清晰性。
我们的第二个写作技巧也与手册的交互性有关。你可以通过调整指令的布局来增强这种品质。
比较以下两个句子，考虑哪个听起来更好。
- 滤网清洁后，盖上盖子。
- 清洁滤网并盖上盖子。
如果你和普通人差不多，你可能认为第二个句子更清晰——这就是技术写作中主动语态的力量。
用被动语态编写的指令需要更多精力去理解，并使手册读起来乏味。正因如此，技术作家更喜欢使用主动语态，如下所示。
