用户文档编写最佳实践

我注意到很多团队在构建产品文档时容易忽略一个根本问题：文档不是写给自己看的，而是写给用户看的。可现实往往是，文档要么堆满行业黑话，要么结构混乱得像个信息垃圾场。用户翻半天找不到答案，最后只能转头去问客服。这中间流失的不仅是用户耐心，更是产品口碑。所以别小看产品手册建设这件事，它直接决定了你的产品是否“好用”。好的文档应该像一位耐心的向导，用最平实的语言，让用户一步步上手。Baklib 在文档协作和结构化发布上做了不少打磨，目的就是让这件麻烦事变得简单点。

要写出最棒的用户文档，关键之一就是知道你在为谁写。了解目标受众能决定你重点阐述哪些主题、如何行文等。简而言之，你对受众的熟悉程度决定了用户文档是否能达到其主要目的。你大概知道这是什么意思，但我们还是引用 David Oragui 的定义来提醒一下：

换句话说，用户文档必须对其受众有用，而只有了解他们是谁，你才能做到这一点。不过，正如 Purdue Online Writing Lab 的 H. Allen Brizee 和 Kety A. Schmaling 所指出的，这不是一刀切的情况。考虑到这一点，我们来看几个为不同受众写作如何产生不同结果的例子。

例如，Shake 是一款用于报告应用程序崩溃和 bug 的工具，其用户是开发人员、软件工程师以及其他参与软件开发的人员。因此，Shake 的用户文档就是针对这些技术娴熟的受众编写的，其中包含类似下面的部分。没有技术知识的人很可能大部分都看不懂。这完全没问题，因为文档是针对 Shake 的目标受众量身定制的，他们熟悉作者使用的术语。

另一方面，为 Jira（一款项目管理工具）编写文档的作者则面对不同的目标受众。Jira 适用于各行各业协作项目的团队，但主要针对采用 Agile（一种特定的项目管理方法）的团队。因此，Jira 的用户文档是针对熟悉 Scrum、Kanban、backlog、sprint 等术语的受众定制的。关键在于，作者必须了解目标受众的样子，因为用户文档的效果取决于作者能否根据读者调整文本。只有明确了目标受众，才能降低创建无用且难以理解的文档的风险——换句话说，就是完全偏离目标的文档。

创建用户文档时，应确保结构逻辑清晰。随意将大量信息堆砌到文档中对任何人都没有好处。文档结构对其可用性至关重要。最好的用户文档在结构上应让用户能够轻松导航、扫描并找到所需信息。因为如果你的写作技巧超群且倾注了大量心血，但结构让用户很难找到需要的内容，那也无济于事。用户不会坐下来把一本操作指南从头读到尾。根据 Jakob Nielsen 的分析，用户平均只阅读网页上约 20% 的文本。因此，当他们打开用户文档时，必须看到逻辑清晰的结构。

首先，目录能提供很大帮助。它列出了用户文档中的章节，用户可以看到感兴趣的信息在哪里。例如，Fitbit 为其所有产品和软件提供了用户手册，每本手册都有类似下面的目录。你可以看到，它包含非常描述性和清晰的标题和子标题，这是另一个有用的元素。而且，考虑到是在浏览器中而非纸上，如果你让标题和子标题链接到相关章节，导航会更加方便——Fitbit 的文档就是这样实现的。

创建逻辑结构还意味着从基础信息开始，逐步深入到高级功能。你不希望在用户掌握产品基础之前就用太复杂的内容让他们困惑。Trello 在文档中做得非常好。他们将指南组织成九个步骤。可以看到，这些步骤遵循自然的学习曲线。首先，用户学习 Trello 面板基础、如何创建第一个项目等。最后，他们熟悉了产品，足以调整管理控制、了解高级版本并浏览技巧。这就是结构良好的文档，它允许逻辑推进，使其成为用户的极佳资源。

技术写作者的基本技能之一是用清晰简单的语言向读者传达技术信息。对目标受众来说难以理解的用户文档根本完不成它的目标——传达读者正在寻找的信息和解决方案。经验丰富的技术写作者 Tom DuPuis 建议，写作者应始终问自己一个问题：“我们的用户是否需要学习如何阅读这篇文档？” 尽管听起来简单，但这个问题正是写作者在创建用户文档时应追求的核心。那么，如何用通俗语言写作呢？有几个元素可以使文档更易懂。

首先，你应该避免使用行业术语。如果你的受众技术知识水平不高，特定术语可能对他们很陌生。然而，完全消除术语并不总是可能。在这种情况下，一定要向读者解释清楚，正如 Kyle Wiens 和 Julia Bluff 建议的那样：“如果你必须使用术语，请尽力提供背景、简短定义，甚至术语表。” 例如，你可以提供产品或服务术语的定义。下面可以看到 Charthop 在其产品文档中的做法。他们有一整章关于术语的内容，在右侧可以看到他们定义的术语。这样，他们通过提供一种以清晰方式定义术语的资源，最大限度地减少了用户中潜在的困惑。

无论你的目标受众是谁，使用通俗语言都是有益的。他们可以是完全初学者或有一定知识，但都会欣赏简单易懂的写作。例如，即使是更复杂的文档，如 Vimeo API 参考，也可以这样写。即使你对 API 一无所知，也能理解上面划线的句子。这种轻松的语气和直截了当的写作方式可以应用于任何产品的文档创建。这只会使其更可用、更吸引人，这是每个技术写作者都应追求的品质。

不同类型的媒体可以很好地补充用户文档，尤其有助于提高理解力，这是技术写作者应始终牢记的。当然，文本应是文档的核心部分，因为它是呈现信息的主要方式。但这并不意味着它应该是唯一的方式。添加视觉元素，尤其是截图和视频，可以丰富文档，并与文本协同，为用户提供出色的体验。正如技术写作影响者 Kesi Parker 所说，它们应相互补充。但是，如果作者已经尽力创建了信息丰富且易于理解的文本，添加媒体又如何能提高理解力呢？很简单。媒体提供了另一种呈现信息的方式，有些信息通过视觉更容易理解和吸收。Monday 是一款项目管理工具，在其文档中大量使用了截图和视频。在关于 Workdocs 的部分，他们使用了屏幕录像来展示操作。这比纯文本描述更直观，也更容易让用户放松下来，集中注意力。

---

Baklib，连接企业数字内容的世界！ 在数字技术的驱动下，企业未来的发展趋势就是互动、协同、连接。未来拥有什么固然重要，但是更重要的是连接了什么，创新 了什么？赋能了什么？ Baklib是一个综合管理的平台，就是在连接企业的所有数字内容。