为您的 SaaS 知识库创建完美的风格指南

介绍

编写支持文档的一个重要部分是如何将其呈现给用户。

为什么？当然，只有内容才重要。

演示之所以重要，是因为专业形象有助于建立用户的信任并激发他们的信心。它还使您的内容更易于使用。

您可能已经有一些帮助内容，但有点不匹配。您的知识库多年来一直在有机增长，并且来自不同的来源。这不是问题 - 但最终，每个知识库都需要自己的风格指南，以便您可以保持内容的一致性和专业性。

当您的内容有多个贡献者且可能不了解您的所有目标和决策时，风格指南尤其方便。你正在用你的风格指南使隐含的显式化。

那么你的风格指南应该涵盖哪些内容呢？

知识库风格指南处理内容的呈现方面：语音和语气、格式、文字、布局。

许多不同的内容源都有自己的风格指南，但 SaaS 知识库包含一些非常特定类型的内容。请务必记住，您可以编写不同类型的文档，包括：教程、操作指南、解释和参考资料。

完整的风格指南需要涵盖许多内容，我们将在本文中详细介绍。特别注意“指南”这个词——这意味着你正在为作家提供一个模板，而不是创建一本硬性的法律书籍。

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

第 1 部分 – 教程

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

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

将教程视为教用户如何做某事的课程。

您决定向用户教授什么内容，目标是让他们尽快安装并运行您的软件。每个教程都应该为您的用户带来切实的结果，向他们介绍使用您的软件的基本过程。

它应该以逐步的格式编写。每一步都应该是实用的，并带来用户可见的进步——而不是纯粹的理论学习。

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

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

开始你的教程

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

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

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

分步格式化您的教程

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

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

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

创建工作教程

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

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

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

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

教程风格

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

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

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

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

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

数字海洋

乌班图

紫藤属

第 2 部分 – 操作指南

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

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

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

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

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

类比：指导驾驶员如何更换轮胎软件示例：如何将数据列表上传到系统的说明

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

开始您的操作指南

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

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

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

编写程序

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

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

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

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

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

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

风格和格式

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

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

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

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

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

条纹

体式

第 3 节 – 解释

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

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

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

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

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

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

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

第 4 节 – 参考

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

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

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

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

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

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

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

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

严格检查准确性

第 5 部分 – 语音和语气

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

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

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

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

不同类型的内容保持一致

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

您使用的常见短语

你写句子的方式

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

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

选词

标点

表情符号

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

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

例如：

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

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

使用现在时

用自信的语言写作

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

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

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

第 6 节 – 术语

每个知识库都使用自己的词典，并且您选择的术语必须在帮助内容中保持一致。术语会教您的贡献者如何正确引用软件的不同部分，以与您想要向外界展示的品牌保持一致。

例如，不要在文章开头引用“小部件”，而只是在后面切换到“doohickey”。考虑创建一个全面的术语表供您的作者参考。

例如，以下是Splunk 文档中的一个方便的可视化示例，解释了编写者应如何引用其软件：

正确使用术语非常重要，因为您正在教用户如何描述您的软件。通常，不熟悉的领域可能会让刚接触您的产品或以前没有使用过您的知识库的用户感到困惑。

术语缺乏清晰度可能会导致无法遵循说明，并导致用户感到沮丧和不满。如果您对某个特定功能的名称有明显的倾向，请遵循您的直觉，而不是想出花哨的名称。越明显越好。

第 7 节 – 词语选择

与术语不同，知识库中的单词选择是指贡献者在编写帮助内容时可能选择的更通用的单词。与任何类型的写作一样，您的语言选择会强烈影响读者从您的写作中获得的含义。

选择单词时需要考虑的一些因素是：

使用缩写（用“don’t”代替“do not”）

选择最简单的词语（“使用”而不是“利用”）

使用只有一两个从句的短句

避免含糊的术语

删除行话并简化技术术语

在代表您的特定品牌时，词语的选择是一个重要因素，并且有助于塑造您的品牌基调。总体目标是选择单词，使内容易于阅读且明确，以便您的用户可以遵循您的说明。

有时需要技术术语来表达您的观点，但您应该谨慎使用它们。始终假设您的读者可能不熟悉该技术术语，当您使用该术语时，请链接到定义。

同样，当您可以使用简单的单词（例如“use”）时，不要使用复杂的单词（例如“utilise”）。您可以使用Hemingway等免费工具来检查内容的可读性。

使用缩写（“don’t”而不是“do not”）可以使您的内容更具可读性，但也会使您的内容更难翻译。因此，带有缩写的内容不太适合国际观众。如果你的语言过于非正式，同样的情况也会发生——对于那些以英语为第二语言的人来说，阅读也会变得更加困难。

第 8 节 – 可扫描内容

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

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

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

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

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

用短标题、句子和段落编写内容前置标题，以便最重要的关键字位于开头附近

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

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

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

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

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

第 9 节 – 标准化您的格式

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

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

字体

颜色

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

强调（使用粗体）

斜体

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

网址

标题

命名 UI 元素

代码片段

文件名

数字或单词

日期和时间

缩写

产品名称

表格

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

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

最后的评论

您可以在风格指南中包含任意数量的部分。您最终得到的结果取决于您的知识库需要包含的信息量。

如果您没有太多内容要发布，或者时间不够，请考虑创建一页样式指南，仅涵盖最重要的注意事项。

另一方面，你可能有很多东西可以分享。例如，您可能需要解释如何为国际读者写作以及如何适应翻译策略。您可能需要指导您的作者如何引用第三方、如何为聊天机器人编写内容、遵循可访问性指南等等。在这种情况下，请慢慢来，根据需要将风格指南分成多个部分。

不要羞于从一些最大的品牌那里获取有关如何编写知识库风格指南的灵感。请留意您喜欢的外观格式。请记住——你们有很好的伙伴。