知识库风格指南完整框架：打造专业统一的内容体验

介绍

在编写支持文档时，如何呈现内容给用户至关重要。尽管内容本身无疑是最重要的因素，但呈现方式同样具有不可忽视的作用。良好的演示能树立专业形象，建立用户信任，激发信心，还能让内容更加易于使用。

随着知识库的不断积累和成长，很多内容源来自不同的团队和部门。因此，保持一致性和专业性尤为重要，这时，风格指南就成了保证内容质量和一致性的关键。通过风格指南，我们可以确保内容风格的一致性，从而提升用户体验。

风格指南处理的是内容的呈现方式，包括语音与语气、格式、文字选择以及布局。无论是教程、操作指南、解释还是参考文献，每种类型的内容都有其特定的写作规则，而风格指南就是为各个贡献者提供统一模板，确保内容的连贯性和高效传达。。

这是一位英语写作大师的一句永恒的名言：“打破这些规则中的任何一条，都比说任何彻头彻尾的野蛮话要早。” ——乔治·奥威尔， 《政治与英语》

第1部分 – 教程：帮助用户快速上手

创建用户文档时，可能遇到的主要内容类型之一是教程。

教程是分步指南，重点介绍一个主题或一小组密切相关的主题。它以学习为导向，允许初学者使用您的软件。

将教程视为教用户如何做某事的课程。决定向用户教授什么内容，目标是让他们尽快安装并运行您的软件。每个教程都应该为您的用户带来切实的结果，向他们介绍使用您的软件的基本过程。它应该以逐步的格式编写。每一步都应该是实用的，并带来用户可见的进步——而不是纯粹的理论学习。

类比：想象一下新驾驶员的驾驶课程，学习汽车的基本功能，例如启动发动机、换档和制动。

软件示例：在Baklib中创建您的第一个知识库，以下是教程写作的一些基本规则：

开始教程

在教程的开头包含文章内容的摘要

告诉您的用户他们可以期望学习什么，以及完成本教程所需的先决条件

专注于提供一种让用户开始使用该软件的方法

分步格式化教程

尝试按照从易到难的难度顺序安排必要的步骤。

仅包含用户完成任务所需的步骤教程中仅包含具体步骤，并避免与实际学习无关的抽象概念。

控制教程步骤的长度——保持简洁但不唐突。

创建工作教程

确认您已经创建了一个工作教程，包括检查它是否在不同的环境中运行。

为您的教程提供一个工作示例，以便用户可以边做边学

在整个教程中包含用户可见的结果，提供有关任务的反馈。

测试您的教程是否可供用户重复

教程风格

仅包含完成任务所需的最少量的解释

不要让你的教程太长或太复杂

在教程期间不要链接到外部网站 - 让您的用户专注于手头的任务

为想要了解更多信息的用户在教程末尾添加“后续步骤”或进一步阅读内容

一些很棒的教程的例子是：

数字海洋

乌班图

紫藤属

第2部分 – 操作指南：解决特定问题

接下来，我们将了解如何编写操作指南。

操作指南看起来与教程类似，但实际上旨在解决软件的特定问题或问题。

操作指南以目标为导向，以一系列步骤的形式呈现，更多地可以被视为故障排除类型的内容。这些文章需要用户预先了解该主题的一些知识，并且旨在实现特定的目标。

它们通常针对的是更有经验的用户，他们想知道软件的某个特定方面是如何工作的。这里的重点是一致性和清晰度。例如，当您的作者引用 UI 元素时，您必须遵守典型约定。

请务必记住，用户正在使用许多不同类型的硬件设备、浏览器或操作系统，因此您需要格式化指令以考虑所有可能性。

类比：指导驾驶员如何更换轮胎

软件示例：如何将数据列表上传到系统的说明

以下是编写操作指南的一些规则：

开始您的操作指南

为您的指南选择一个描述性名称，准确地告诉用户该指南打算解决什么问题

将操作指南格式化为有序步骤列表（1、2、3）在指南的开头总结解决方案，以便经验丰富的用户可以跳到重要部分

专注于使用软件实现实际目标的结果，并解决一直困扰用户的特定问题

编写程序

每个指南中的程序格式一致，以便您的用户可以扫描内容

将您的程序限制为少于七个步骤，以避免信息过载

在发出指令之前描述 UI 中发生操作的位置

在每个步骤中包含最终完成该步骤的操作；例如，选择“确定”

使用与用户可能使用的任何设备相对应的通用输入词；例如，避免单击或滑动以支持打开或选择

您可以使用直尖括号来缩短简单的序列；例如，选择帐户>其他帐户>添加新帐户

风格和格式

用正确的语法和标点符号用完整的句子写下您的指南

在正文中包含标注以突出显示必要的信息 - 例如，执行特定操作将如何影响系统

避免通过链接到其他地方的解释来解释“概念信息”

省略完成任务不需要的任何信息

一些很棒的操作指南的例子是：

条纹

体式

第3部分 – 解释：扩展理解

您可能需要在知识库中使用的另一种文档类型是解释。此类文档甚至可能没有自己的部分，但可以散布在其余内容中。它为您的用户提供有关您的软件的重要知识。解释旨在帮助您的用户理解特定主题，并提供更多背景和上下文。它可以为某个主题提供清晰度和启发，并在“需要知道”的基础上提供比您预期更多的信息。

类比：有关特定车型设计历史的文章软件示例：有关软件背后的设计过程的文章

写出好的解释的一些规则：

提供尽可能多的背景信息并解释“为什么”

不指导用户或包含任何技术参考

使用此类内容来扩展用户对整个软件的理解

使用任何人都能理解的简单语言

第4部分 – 参考文献：技术详细说明

参考指南是一种面向信息的技术文档，描述软件或用户需要了解的软件的任何相关方面。

它可以包括参考材料，例如知识库中使用的术语表，或 API 和 Webhooks 文档，其中包括软件的主要接口/属性/方法。您可以列出软件的技术规格、当前的集成等。

类比：一本涵盖特定车型技术规格的手册

软件示例：Baklib 知识库中使用的术语表

编写参考文档的一些规则：

力求结构、语气和格式的一致性

仅描述相关技术组件，避免指导或解释

使用直截了当、实事求是的语气

严格检查准确性

第5部分 – 语音与语气：展现品牌个性

现在我们已经介绍了您可能需要的不同类型的文档，我们将继续讨论语言的整体呈现。

支持知识库仍然是整个公司品牌的一部分，因此应该以一致的语气和语气编写。但首先，什么是声音和语气？

写作中的声音和语气是两个独立但相关的概念。

声音是您品牌的个性，它是：

不同类型的内容保持一致

您在写作中使用或省略的单词

您使用的常见短语

你写句子的方式

使用标点符号来创建特定的表达式

基调是您的品牌当前特定内容的心态和情感，它通过以下方式表达：

选词

标点

表情符号

声音和语气最终是品牌个性的表达，并且每个公司都会有所不同。对于任何想要创建自己的语音和语气风格指南的人来说， MailChimp 风格指南是一个极好的资源。更好的是，我们编制了一些现实生活中的励志短语，将帮助您开始构建自己的指南。

微软的品牌声音：最重要的是，简单和人性化Buffer 的声音是：相关、平易近人、真诚且包容MailChimp 的声音是：使用另类的幽默和对话式的声音，我们玩弄语言，为他们的工作带来乐趣。我们更喜欢微妙的东西而不是喧闹的东西，喜欢讽刺的东西而不是滑稽的东西。我们不太把自己当回事。Splunk 的声音和语气：Splunk 文档随意和平易近人，但又简洁直接。目标是自信、友好、全面，而不是麻木不仁、甜蜜或复杂。Rackspace 的声音和语气应该：建立信任、激发信心、让事情变得更容易、与 Rackspace 用户建立关系。声音和语气可以分解为更具体的方面，您可以为贡献者进行扩展。

例如：

使用第二人称写给用户并使用祈使语气

使用主动语态使动作的执行者成为句子的主语

使用现在时

用自信的语言写作

提出建议而不是发出命令（“你可以做 X”而不是“你必须做 X”）

使用信息丰富、易于理解且清晰的有用单词和短语

避免将任何负面情况归咎于用户

第6部分 – 术语：保持一致性

术语的一致性至关重要，特别是在面对具有技术性背景的产品时。统一的术语能帮助用户理解并准确表达软件的功能。

术语使用的基本规则：

清晰性： 确保术语明确且统一，避免混淆。

一致性： 在整个知识库中使用相同的术语，避免随意更改。

第7部分 – 词语选择：简洁与明确

知识库中的词语选择直接影响内容的可读性和易用性。简洁、清晰的语言能让用户更容易理解和执行任务。

如何选择合适的词语：

简洁性： 使用简单直白的词汇，避免复杂的术语。

避免含糊： 确保词语表达清晰，不给用户带来困惑。

第8部分 – 可扫描内容：适应网络阅读习惯

SaaS 知识库旨在在线阅读，并且应该以吸引网络用户的方式编写。众所周知，网络用户喜欢扫描内容而不是阅读，并直接浏览到与他们相关的部分。因此，您应该尽可能地分解内容，并使用格式来突出显示内容中最重要的部分。

以下是创建可扫描网页内容的一些基本规则：

在文章开头展示最重要的内容（“首屏”）

在长内容的开头包含导航元素或目录

您可以在操作指南的开头包含解决方案的简短摘要，以便更有经验的用户不必阅读整篇文章

用短标题、句子和段落编写内容

前置标题，以便最重要的关键字位于开头附近

使用粗体格式突出显示关键词或短语

使用标注来突出显示警告或其他重要信息块

使用有序或无序列表作为信息序列；即任何类型的程序

要求您的贡献者以可扫描的格式进行写作可以为您的知识库最终用户带来更好的可用性。

尽可能将内容分成几个部分并以基于主题的格式编写非常重要。这样您的内容就可以轻松扫描，也可以在其他位置重复使用。

第9部分 – 标准化格式：确保一致性

知识库内容应该一致地呈现，并且在写作中需要控制许多因素。正是这些小事情让您的知识库给人留下了专业资源的印象，并且使您的内容更容易吸收。

例如，以统一的方式使用特定的样式，包括：

字体

颜色

大写（包括句子大小写或标题大小写的使用）

强调（使用粗体）

斜体

您还需要标准化特定文本元素的格式：

网址

标题

命名 UI 元素

代码片段

文件名

数字或单词

日期和时间

缩写

产品名称

表格

标准化使您的内容更易于阅读并具有连贯性。它使您的文本更加明确，并在用户在您的内容中搜索信息时为他们提供帮助。

没有唯一正确的方法来格式化您的内容。主要关注的是保持您自己的内容的格式一致。

结语

在编写支持文档时，制定明确的风格指南并坚持使用它，可以帮助提升内容的一致性和专业性。无论是教程、操作指南、解释还是参考文献，明确的语音与语气、清晰的术语使用、简洁的语言和一致的格式都能确保您的知识库为用户提供顺畅、高效的体验。

Baklib AI+内容云平台，作为一款 All in Content 的企业级云平台，致力于帮助企业构建多场景全渠道的数字体验。通过独创的资源库、知识库、应用库三层架构，Baklib 无缝连接品牌、产品、客户和员工，助力企业走在 AI 时代的前沿，为用户提供智能化的内容管理和支持