技术写作流程：分步指南

我是 Ken，Baklib 的研究员。经常有产品经理问我：为什么我们的产品手册总是没人看？不是用户不爱学习，而是大多数技术文档从根上就错了——它们不是写给读者看的，而是写给发明者自己看的。真正高效的产品手册建设，核心在于理解你的读者、明确文档目标、深入研究主题、先列提纲再动笔。这些步骤听起来简单，但多数团队在第一步就栽了跟头。Baklib 的产品手册建设方案，正是围绕这些关键环节设计的，帮助团队快速产出清晰、实用的文档。

技术文档的编写过程绝非易事。
除了拥有出色的写作技巧，你还需对产品有实操经验。
此外，不准确或劣质的文档会严重损害产品价值，并伤害公司声誉。
幸运的是，这个过程是可以掌握的。
本文将为你提供一份分步指南，帮助你为产品的每个功能创建有价值的、聚焦的、经过充分调研的文档。
首先，我们要从技术写作过程中最重要的人物开始：目标读者。

了解受众对任何类型的写作都很重要。然而，技术写作者应意识到，定义读者是谁是工作的关键。
如果你不知道为谁而写，文档可能完全无用。
考虑这份关于 API 的技术文档：
虽然开发者能轻松理解其中的信息，但背景不同的人却完全摸不着头脑。
通常，读者可分为以下几类：

这些类别的成员阅读文档的目标不同，技术知识水平也不同，因此你需要根据受众类别调整写作方式。
一个很好的方法是创建读者画像。
简单来说，画像是虚构的读者。
它们为你的目标受众赋予人性面孔，帮助你在构建和撰写文章时保持读者视角。
来看一个实际例子。
Tails 是一个旨在保护用户免遭监视和审查的便携操作系统。
Tails 团队使用多个画像来构建网络，从而始终知道如何满足受众需求，并写出易于理解的文档。
以下是他们的主要画像：
如你所见，画像包含受众可能使用的技术类型以及他们的目标，这有助于技术写作者创建满足需求的文档，并使用读者已熟悉的概念和术语呈现技术信息。
以下是最终面向 Tails 用户的文档案例，每篇文章都以上述画像为出发点。
关键在于：文档的不同用户需要不同的方法。
因此，请找出你的读者，尽可能详细地定义他们，并在写作时始终考虑他们的需求。

说到文档目标，这是你在落笔前应定义的另一个重要方面。
在进一步解释之前，有必要提醒自己：技术写作的主要目标是“简化复杂”。
因此，无论你写何种类型的文档，都要牢记这个首要目标。
然后，思考你还想通过写作实现什么。
是想告知读者产品的优点和用途，还是想帮助他们安装和使用？
这个问题的答案应指导你的写作，帮助你保持主题，让工作更容易。
来看 ChartHop 的两个例子，看看不同的目标如何催生不同的文档。
首先，ChartHop 知识库中有一篇文章解释了不同的产品套餐选项。
可以看出，文章列出了可用套餐并解释了每种套餐的能力。
这篇文章为试图选择最合适方案的客户提供信息和建议。
另一方面，这篇文章提供了使用平台的具体说明。
文章包含界面截图和关于如何使用软件不同功能的清晰指示。
目标是学习使用产品的读者肯定会从中受益。
想象一下，如果这些文章没有目标会怎样。
例如，关于导航的文章可能被写成反映应用的导航功能有多独特，或者开发者投入了多少时间。
这对使用产品的读者来说毫无用处，对吧？
这就是带着明确目标写作带来的巨大差异。
在目标明确的情况下写作，你确保了为正确的用户创建正确的内容。

在明确定义读者和目标后，是时候深入研究主题了。
这是不可跳过的一步，因为你不想向读者提供不准确的信息。
提供不准确的技术文档会损害公司声誉。
依赖文档的最终用户会在使用产品时遇到问题，导致用户体验不佳。
最终，这可能导致用户流失并向他人抱怨，使公司损失收入和订阅用户。
以下是一个真实案例：
因此，只写你知道的内容并提供确定的指示极为重要。而做到这一点的唯一方法是在开始写作前进行彻底研究。
你可以通过探索你要写的产品和功能来开始研究。熟悉它的用法，了解其方方面面。
一旦你知道如何使用某样东西，向他人解释特性就容易多了。
接下来，确定主题专家（SME）。他们可能是开发你所写功能的人。
毕竟，谁能比设计该功能的专家更好地解释产品功能的工作原理呢？
准备好问题，安排与 SME 的会议，填补知识空白。
如果你想为 SME 会议创建良好的工作流，可以尝试使用会议应用（如 Hypercontext）轻松安排会议并设置议程，确保每个人都做好准备。
最后，进行一些二手阅读。利用互联网和 Google 查找关于你正在写的话题的最近专家文章。
如你所知，网上有很多错误信息，因此要反复检查来源的可靠性。
作为专注于单一项目的技术写作者，你可能会经常回顾优质文章和研究，因此建立一个相关文章库是个好主意。
你可以使用 Raindrop 等书签工具来实现这一目的。
通过亲身体验产品、获得专家帮助以及大量阅读，你的研究覆盖了所有方面，可以自信地开始写作了。

创建大纲是确保文章易于导航、结构清晰、帮助读者快速找到所需信息的绝佳方式。
你不想向读者呈现枯燥的文字墙，因此要确保大纲逻辑清晰且对用户有帮助。
首先为文章拟一个实用、可操作的标题。让它清晰明了，以便读者立即知道他们找到了所需内容。
以下是一个好例子：
接下来，将主题拆分为若干子部分。这些可作为文章标题，并构成目录。
文章主体的大部分内容都位于这些标题下，它们代表了文章涵盖的主题。
那么，还需要什么？
没有引言和结论的文章是不完整的。你的引言将引导读者进入文章，好的结论通常总结要点。
在文章开头列出读者应具备的前提条件也是一个好做法，这有助于读者理解并正确运用你传递的知识。
以下是同一篇文章的前提条件列表：
瞧！你的大纲完成了，现在开始写草稿容易得多，因为大纲将成为工作的路线图。
最后一点。当你撰写同一主题的许多文章时，最好对所有文档使用类似的大纲。
这不仅确保风格一致，还能为你节省时间。

---

Baklib在将生成式人工智能和企业搜索功能集成到我们的知识管理平台方面所取得的重大进展。通过简化关键信息的检索过程，我们使员工能够更快地做出明智决策，最终提高生产力，推动组织成功。Baklib 擅长管理非结构化数据，确保所有内容都是可访问的、相关的和最新的。