技术写作中的极简主义：一份指南
浏览：0
巴克励步
我发现很多技术团队在搭建产品手册时，总是陷入一个误区：恨不得把每个按钮、每个字段都写进文档，生怕用户看不懂。结果呢？用户翻几页就放弃了，宁愿自己瞎点，也不愿读那厚厚一本说明书。这其实就是资源错配——花了大价钱写文档，却没人看。我在处理这类问题时，一直推崇极简主义。产品手册建设不是越全越好，而是要精准、可行动、易复用。Baklib的多站点发布和内容复用能力，正好能支撑这种思路：用标准化的组件和简洁的指
我发现很多技术团队在搭建产品手册时，总是陷入一个误区：恨不得把每个按钮、每个字段都写进文档，生怕用户看不懂。结果呢？用户翻几页就放弃了，宁愿自己瞎点，也不愿读那厚厚一本说明书。这其实就是资源错配——花了大价钱写文档，却没人看。我在处理这类问题时，一直推崇极简主义。产品手册建设不是越全越好，而是要精准、可行动、易复用。Baklib的多站点发布和内容复用能力，正好能支撑这种思路：用标准化的组件和简洁的指令，让用户快速上手，而不是淹没在文字里。下面这篇文章来自我对行业最佳实践的梳理，希望能帮你重新思考产品手册的写法。
技术写作者几乎总是被教导要过度解释他们正在记录的概念和任务，以确保用户永远不会感到沮丧或困惑。
但这是否总是记录的最佳方法呢？如果用户不想阅读一页又一页的产品指南来操作你的软件呢？
在本文中，我们将向你介绍另一种技术写作方法：极简主义。
💛🧡🧡客户评价：Next.js 的 Baklib 模板和指南有点难以理解，因为似乎有不少具有不同功能集的模板和指南。希望设置过程总体上能够更加简化和清晰。我想我已经浏览了 4 个官方模板，它们在设置获取函数等方面都有完全不同的逻辑。不过，部分原因可能与 Next.js 本身最近的重大变化有关。手动输入模式可能很乏味，尤其是当涉及到条件验证等更复杂的逻辑时。像竞争对手的产品（例如 Baklib ）这样的可视化界面会很棒。设置实时编辑和草稿预览似乎过于复杂。根据我的经验，演示模式总体上被证明是相当不稳定的。
让我们看看当技术文档轻微支持用户且不干扰他们学习操作软件产品的过程时会发生什么。
技术写作中的极简主义是什么
创建技术文档的原则相当简单。
由于新手没有处理特定技术产品的经验，他们需要查阅技术文档才能成功学习如何使用它。
经典的文档方法非常字面地遵循这一原则。
在这种方法中，每个概念都被过度解释，每个动作都被分解为微步骤，以确保用户永远不会感到困惑或不确定下一步需要做什么。
所有这些似乎都非常合乎逻辑，但研究表明，这种经典的文档方法并不能真正反映真实技术用户的行为。
观察人们如何与计算机系统交互时，著名信息科学家John M. Carroll注意到一个特殊的模式。
他的研究表明，人们在与系统交互时拥有的知识和经验越少，他们查阅文档的次数就越少。
Carroll继续解释说，人们本能地想利用已有的经验和知识来学习如何使用产品。
然而，这种现有的心理模型可能与书面说明发生冲突，导致大脑拒绝指令并相信自己的经验。
他将这种现象称为“意义构建悖论”：
人们生活在一个比一系列步骤更直接的现实世界中——一个为他们的所有行为提供丰富背景和惯例的世界。他们不断尝试、思考、将自己已知的与正在发生的事情联系起来，并从错误中恢复。简而言之，他们忙于学习，以至于很少使用说明。这就是意义构建的悖论。
Carroll对此问题的解决方案是：剥离文档中所有不必要的信息，使其以行动为导向而非描述性，并使用简单的语言来解释产品的工作原理。
这种新方法背后的理念是支持用户接触计算机系统，而不是通过让他们耗费大量精力阅读无尽的指南、手册和解释来干扰他们的学习过程。
于是，创建文档的极简主义方法诞生了，并很快被IBM、Microsoft、HP和Cisco等技术巨头采用。
极简主义方法至今仍是许多当代软件等技术文档技术写作者的首选方法。
以下部分将解释为什么极简主义在文档中持续存在，以及如何让你的技术写作更加极简，以更好地服务用户。
为什么应该使用极简原则
重申之前的观点，当读者面对过多的文档时，他们往往会放弃阅读，并尝试自己摸索产品。
这有两个主要问题：
- 你的文档现在对用户毫无用处，意味着你浪费了创建它的资源。
- 用户有可能以错误的方式使用你的产品，意味着他们可能无法从中获得任何价值。
因此，采用极简主义文档方法的最大好处是资源分配更合理。
想一想。创建大量文档需要花费大量资金。事实上，在科技行业，文档的价值高达整个产品设计成本的10%。
这个数字考虑了创建、分发和维护知识库中大量文档所涉及的资源和任务。
但采用极简主义方法，可以显著降低这一成本，同时不损害用户在开始使用产品时的积极体验。
恰恰相反，用户无需浪费时间筛选华丽的语言和冗长的描述来寻找所需信息，而是可以花更多时间与产品交互，从而提高他们对产品的参与度。
极简主义也非常符合敏捷软件开发方法，这是当今世界各地软件公司使用的现代方法。
在敏捷方法中，文档是在开发过程的后期创建的（即时文档）。
因此，它必然不会过于详细，因为根本没有时间创建包含所有细节的全面文档。
相反，敏捷和极简文档只包含用户操作产品所需的内容，别无其他。
因此，通过保持文档的极简性，你正在使你的努力与软件开发过程保持一致，并使你的团队能够轻松转向、做出更改并在产品开发过程中调整文档。
总而言之，极简文档资源密集度更低，用户更容易消化，但不会损害用户体验或产品采用率。
它对技术写作团队也有好处，因为它使他们的工作与开发团队的工作保持一致，并使他们能够在文档过程中更具适应性和响应性。
这使得技术写作者能够更紧密、更有效地跟随软件开发过程。
如何在技术写作中实现极简主义
既然我们已经确定技术写作中的极简主义是一种安全且高效的文档方法，不会损害你的团队或最终用户，那么让我们来看一些极简原则。
这些原则同时也可作为可操作的建议，你可以轻松应用它们来精简文档，同时使其更有效和更有影响力。
使文档中的任务以行动为导向
很多文档强调“知道”的概念而不是“做”的概念。
在这种方法中，你描述产品的性质、特性和特点，使用户了解他们可以用产品完成的所有事情。
以Slack关于频道的文章为例：
该文章提供了基本定义，并说明了可以使用通信应用的这一功能做什么。
这是一个很好的资源，但它并没有真正告诉用户如何完成某件事，或者需要采取哪些步骤来完成任务，比如创建频道。
换句话说，它不是以行动为导向的，意味着用户可以在没有它的情况下继续前进。
接下来，我们将回顾同一来源的另一份文档；它涵盖了将人员添加到Slack消息中。
注意这份文档是多么简洁和可操作。它为用户在需要完成任务时提供了清晰的前进方向。
如果用户不知道如何完成这个特定任务，这就是一份他们无法继续工作而离不开的文档。
所以你可以看到，有些类型的文档用户没有它也可以。
其他文档，那些向他们展示如何做某事，而不是描述软件功能的文档，才是对他们绝对必要的。
对于极简主义的文档方法，关注后者——以行动为导向的文档。
使部分内容可复用
极简文档成为一种非常有用的方法的一个特定场景是较大的公司，它们同时开发多个产品，或者开发一个具有大量功能的单一项目。
在这些情况下，极简方法涉及使部分文档可复用，以便它们可以轻松应用于多个项目，而无需对文档进行更改。
那么，如何使你的内容可复用呢？
最简单的方法是剥离所有特定信息，例如产品的名称和/或版本。
通过这样做，你将拥有一组可以复用和根据需求调整的通用文档。
下面是来自IBM的可复用文档示例（你可能还记得，IBM是最早采用极简文档的公司之一）：
这是IBM Operational Decision Manager的安装指南。如你所见，此操作的信息架构尽可能通用。
它使用了适用于所有安装指南的一致标准，包括组件、初步步骤和不同的安装选项。
产品从未被提及名称，而只是被称为“产品”。
建立可复用内容的档案本身可能看起来是一项艰巨的任务，但如果你使用高质量的文档软件，实际上很容易做到。
例如，Baklib提供了可复用的内容功能，使你能够创建内容片段，保存它们，然后轻松粘贴到文档中。
对于像IBM这样的大公司，使内容可复用可以显著减少需要生成的文档数量。
文章遵循类似的大纲，并尽可能使用通用名称，以便只需要添加最少的特定信息即可使文档工作。
使用标准化语言
极简文档的另一个特点是标准化语言。
这一原则旨在将你使用的术语数量减少到最低限度，以增加文档的一致性并避免用户混淆。
原因如下。
构建和使用软件自带词汇和术语，这些词汇和术语对最终用户来说并不总是自然易懂，即使他们具有开发知识。
💛 🧡 Baklib 是一个统一的内容中台平台，可提供更好的数字体验。为了满足现代参与日益增长的需求，您需要一个现代的内容管理系统。使用 Baklib 解决渠道扩散、本地化、个性化等问题。Baklib 由三个主要组件组成：Baklib 知识库可以根据团队的需求量身定制内容工作区，内置他们期望的所有可视化文档管理工具。Baklib 资源库则是一个无需操作的存储和分发层，可同步内容和数据，供整个组织的团队使用。其精确的查询语言支持在任何地方重复使用内容。Baklib 应用库的模板和 API 旨在帮助开发人员蓬勃发展。它们与现有的 CI/CD 工作流程无缝集成，支持编程模式编码，并提供实时双向同步。
