作为知识库的贡献者，您用文字帮助着五亿用户。这是一项艰巨的工作。用户从世界各地来到知识库，他们期望得到简单的解决方案，但我们也希望用我们的声音给他们带来惊喜。您该怎么做呢？以下是我们在研究中得出的一些心得。

语气

写作时要牢记品牌形象。Mozilla 倡导用户选择。我们信奉自由和灵活性。我们重视隐私和安全。我们是一个由社区驱动的非营利组织，拥有来自世界各地、价值观相同的贡献者。

您不必在每篇文章中都强调这一点。这只是在描述功能时需要记住的事情。

写作风格

为非技术性的普通读者写作。

我们希望我们的文章能被所有人使用，而不仅仅是高级用户。这意味着我们是为普通大众写作，而不是为那些非常熟悉计算机技术和术语的人写作。假设您写作的对象在没有分步说明的情况下，不知道如何更改首选项或添加工具栏按钮。此外，我们还应假设他们没有更改任何默认的应用程序或操作系统设置。

总而言之，您应遵循以下准则：

1. 保持简短。 人们来到知识库是为了寻找快速的解决方案。他们可能不关心工具的内部工作原理——他们只想知道他们应该怎么做来解决问题。大胆地删减一些词语。看看用更少的词能表达多少意思。这就像写诗一样！
2. 保持清晰。 避免使用行话。要具体。在标题和文章中使用读者会用的词。如果您 13 岁的侄子看不懂，那就写到他能看懂为止。更详尽的指南请参见下一节。
3. 友好、有趣、有同理心。（简而言之：要有人情味。） 好吧，用户来寻求支持时并不期望获得乐趣。这正是这种做法的强大之处。用一点幽默来点亮用户的一天。但要小心，不要为了使用有趣的隐喻或表达而牺牲清晰度。如果您不确定如何平衡这一点，只需写出直接的说明，并在引言或结论中使用这种语气。
4. 讲一个故事。 要有开头、中间和结尾。但不要写小说（见准则 #1）。
   • 开头： 这为读者提供了一些背景。这篇文章是关于什么的，我为什么要关心？保持简短。
   • 中间： 说明放在这里。这应该回答“我该怎么做？”
   • 结尾： 文章或功能是否有后续步骤？告诉读者如果想了解更多，接下来应该去哪里。

更全面的指南请阅读下一节。

写作风格（综合）

• 对话式写作风格 – 使用非正式、主动的风格，类似于您与人当面交谈的方式。
• 幽默和情感 – 使用幽默很好，但有时很难或不可能本地化。像惊喜和“我不知道这个/原来如此！”这样的情感可能更容易融入。
• 多种学习风格 – 就像在学校一样，人们的学习方式各不相同。此外，以多种方式表达相同的内容对每个人都有好处。
• 重复 – 当您用不同的方式、通过不同的媒介解释某件事时，您显然也在重复它，这是帮助人们记住重要内容的另一个好方法。
• 图片和视频 – 使用图片和视频配合文字进行解释，不仅是亲身帮助之外的最佳方式，也是融入多种学习风格和重复的简单方法。然而，过多的图片会使文章的本地化更加困难，所以请尽量只在对某个步骤或概念有帮助时才添加图片。例如，对于点击按钮的步骤，您可以说“点击 OK”，而不是添加该按钮对话框的截图。
• 实践活动 – 尤其是在教程中，给人们一些有用的事情来完成是很好的。阅读说明并理解过程是一回事，但提醒并让人们尝试一下通常也很有帮助。

文章类型

为我们的知识库文章使用一致的内容类型有很多好处，包括便于导航、提高清晰度和组织性，此外还有助于我们更有效地创建内容。我们正在过渡到将外部知识库文章分为四种类型，每种类型都有特定的用途：

• 关于：这些文章解决“什么是……”的问题，提供基本信息以帮助读者理解一个主题。
• 操作指南：这些文章侧重于回答“如何……”的问题，指导读者完成实现特定目标或程序所需的步骤。
• 故障排除：这些文章通过解决与问题排查相关的“如何……”问题，帮助用户识别、诊断和解决他们在使用产品、服务或功能时可能遇到的常见问题。
• 常见问题解答：这些文章包含对单个主题的常见问题的简明回答，这些问题可能不适合放在其他单个知识库文章中，为常见查询提供了快速参考。

从一个有效且描述性的标题开始

一个精心制作的标题不仅仅是一个标签；它是用户与您的知识库文章的第一个接触点。一个好的标题不仅应该吸引读者的注意力，还应该作为文章内容的简洁而信息丰富的预览。在为 SUMO 创建标题时，请考虑以下几点：

• 清晰和描述性： 匹配文章内容和用户搜索的内容。要简洁，但要以用户为中心。
• 包含关键词： 加入相关关键词以提高搜索引擎可见性并帮助用户找到您的文章。
• 简洁性： 保持标题简短，同时仍提供足够的信息。较短的标题通常更便于用户使用。尽量将标题保持在 60 个字符左右。
• 面向行动： 在适用时使用动词，以表明用户可以做什么来解决问题或实现目标。避免在标题中使用动名词（以“ing”结尾的词），以确保它们保持面向行动。避免使用包含“如何……”的标题。

写好引言

与标题和目录一样，引言可以帮助用户确定他们是否来对了地方。

• 对于“关于”类文章：提供概念的文字概述或定义，并侧重于用户为什么应该关心它。
• 对于“操作指南”类文章：提供任务的文字概述或定义，并侧重于任务的重要性或好处。
• 对于“故障排除”类文章：描述用户可能遇到的具体问题或症状。使用清晰简洁的语言，尽可能避免使用技术术语。

请记住，一个好的引言通常可以作为一个好的搜索摘要。通常您可以直接将其复制到“搜索结果摘要”字段中，就完成了。

有效地组织文章

这里的总体思路是，尝试从简单到复杂地构建技能，同时尽量将大多数人需要的信息放在文章的顶部。因此，一个简单、常见的解决方案通常应该放在一个复杂或边缘案例的解决方案之前。

让分步说明易于遵循

在编写分步说明时，要记住的主要事情是，要小心地包含完成任务所需的所有操作。例如，如果在选择一个首选项后必须点击 OK 才能进入下一步，请务必将点击“OK”作为该步骤的一部分。 需要考虑的其他事项：

• 总有多种方法可以实现一个结果。我们应该始终选择最方便用户的方式，尽可能使用图形用户界面和菜单。
• 在描述如何访问用户界面时使用完整的句子。
• 在给出说明时包括预期的结果（例如，点击“OK”，窗口将关闭。）。

可读性

文本必须具有可读性。为此，您必须：

• 将文章分成带有副标题的逻辑/语义小块。
• 使用编号或项目符号列表。
• 写简短或相对简短的句子。
• 避免写大段落。

文本量没有限制。材料越多越好；但是，您不应该人为地扩充它。只提供有用、有价值和必要的信息。

如何链接到第三方软件的外部文档

在创建或更新涉及第三方软件（如操作系统或外部应用程序）内操作的文章时，向用户提供准确可靠的信息至关重要。然而，在我们的文章中包含这些软件的直接步骤可能会带来挑战：

• 信息很快过时： 第三方软件的更新可能会使我们的说明过时，从而可能迷惑或误导我们的用户。
• 资源密集： 持续监控和更新多个外部平台的步骤需要大量的精力和资源，这可能并不可行。

最佳实践

为确保我们的用户获得最可靠和最新的信息，同时又不至于耗尽我们的资源，请遵循以下最佳实践：

• 链接到官方资源： 每当说明涉及第三方 software 时，请找到软件制造商提供的官方文档或帮助文章。链接到这些资源，而不是直接在我们的文章中写出步骤。
• 提供背景信息： 简要解释为什么您要将用户引导到外部页面（例如：“有关调整系统设置的最新和最准确的步骤，请参阅官方 [软件名称] 支持页面”）。
• 定期检查链接： 虽然我们的目标是减少对第三方说明的维护，但定期检查外部链接是否仍然有效仍然很重要。如果您发现链接已过时或损坏，请查找官方文档的更新链接并提交修订。
• 关于外部内容的免责声明 当将用户引导到外部链接时，请明确说明他们将离开 SUMO，并且我们不对外部网站的内容负责。一个简单的免责声明或注释即可（例如“点击此链接将重定向到非 Mozilla 运营的外部网站。”）。

示例

假设您正在写一篇关于配置 Firefox 功能的文章，该功能依赖于在 Mac 上更改系统级设置。您可以在文章中这样写，而不是直接概述步骤：

"有关在 macOS 上调整系统偏好设置的最新步骤，请访问此指南查阅 Apple 官方支持文档。请注意，点击该链接将引导您至一个非 Mozilla 运营的外部网站。"

这可以确保您遵循的是直接来自源头的最新说明。

技术准则

• 要了解如何实际创建新文章，请参阅创建新的知识库文章。
• 要了解如何编辑现有文章，请参阅编辑知识库文章。
• 有关知识库如何工作的概述，请参阅关于知识库。
• 有关文章文档的完整列表，请参阅改进知识库。

标题

• 标题长度：Google 的搜索结果页面将显示最多 60 个字符。如果需要，您的标题可以更长，但请确保您的重要关键词包含在前 60 个字符内。
• 大小写：使用句子式大写。标题中的第一个单词以及专有名词和名称应大写，而不是每个主要单词都大写。使用“句子”式，而非“标题”式（这也适用于章节标题）。有关其他大写规则，请参阅下面的样式指南和复制规则部分。
• 不要在文章标题中使用冒号，因为它会阻止创建指向该文章的维基链接（bug 749835）。还要确保文章标题中没有多余的空格，这也会导致维基链接无法正常工作。
• 尝试变换您命名文章的方式。不要在每个标题中使用相同的词语或短语。例如，不要总是以“如何”开头，并避免使用“ing”式的任务名称，如“设置主页”。
• 请记住，整个解释不必都放在标题中。您可以使用摘要为用户提供有关文章内容的其他信息。

Slug

当您创建新文章并输入标题时，SUMO 将自动创建一个 slug（文章 URL 末尾 kb/ 之后的部分）。审阅者可以编辑现有文章的标题，但 slug 保持不变，除非手动更改（这是设计使然）。slug 有 50 个字符的限制。空格会呈现为破折号。slug 应与标题保持一致，但考虑到更严格的空间限制，不必完全相同。

修复 slug

请务bi检查自动生成的 slug 的末尾。有时一个单词会被截断，或者它以破折号结尾。请修复这类问题。

更新现有文章的 slug

当您更新现有文章的标题时，请保持当前的 slug 不变，除非新标题代表了不再与现有 slug 一致的重大更改。保持 slug 的一致性有助于避免链接损坏并保留 SEO 价值。

类别、产品和主题

在大多数情况下，一篇文章属于“操作指南”或“故障排除”类别。偶尔，我们会写其他类别的文章，例如“如何贡献”类文章（如此文）。文章的历史页面将显示类别。

文章也“与”至少一个产品相关。它们还属于一个主“主题”，并可选地属于一个“子主题”。

关键字

文章中的关键字字段可用于改善 SUMO 上的搜索结果。但它只应在特定情况下使用，因为滥用实际上会损害搜索。我们很少需要使用关键字。有关详细信息，请参阅如何通过关键字提高文章的搜索排名。

写好搜索摘要

文章摘要与标题一起，帮助用户判断一篇文章是否能回答他们的问题。我们称之为“用户信心”，它直接影响点击率。即使我们将正确的文章排在搜索结果列表的顶部，用户也需要在大脑中将搜索查询与我们显示的结果联系起来，才能点击进入文章。

操作指南文章的摘要应包括文章涵盖的主题。故障排除文章应尝试包括症状。此外，摘要应遵循以下准z则：

• 简短扼要。还记得分类广告吗？就像那样写。搜索引擎可能会截断任何超过 140 个字符的内容。如果您使用更长的摘要，请将重要信息放在开头。注意： 当摘要达到 140 个字符时，知识库软件将显示剩余 20 个字符，因为内部搜索限制为 160 个字符。
• 不要使用维基标记。
• 不要在每个摘要中都使用“本文解释”。尽可能变换说法。可以考虑使用其他一些短语：
  • 我们将向您展示
  • 我们将解释
  • 本页解释
  • 本文描述
  • 了解如何

步骤数量

在引导用户完成一个过程时，请考虑使用有序列表（编号列表）。通常，将总步骤数保持在六到七步的范围内是一个好习惯。

平行结构

为您写的每一步都使用相同的措辞或词语模式。平行结构在知识库文章中很重要，因为它使内容清晰易懂。当相似的元素具有一致的格式时，用户可以更顺畅地理解和完成任务。这种结构简化了说明，减少了错误，并确保信息得到有效传达。

例如：

1. 找到Firefox 关闭时清除历史记录。如果已选中：
   1. 点击 Settings… 按钮。
   2. 确保表单和搜索历史 未 选中。
   3. 点击 OK。

方向提示

方向提示是指引导用户到用户界面中需要执行特定操作的具体位置或位置的参考或指示。这些提示帮助用户更有效地导航和与软件、应用程序或网站互动。它们通常包括“在右上角”、“在左侧菜单中”或“在搜索栏下方”等短语，为用户提供了清晰的位置感，以便找到并执行操作。

在您的知识库文章说明中，请确保在操作之前提供方向提示。例如，不要说点击按钮，而应使用在右上角，点击按钮。这种格式有助于用户轻松地在界面中定位和执行操作。

样式指南和复制规则

就像我们之前说过的，您在写作时应该使用主动、对话式的风格。避免说“如果用户的书签丢失了”之类的话，而应该说“如果您的书签丢失了”。以下是您在撰写支持文章时可能遇到的其他常见样式和复制问题： 始终使用 Mozilla 界面中出现的术语。 例如：

• Plugins 没有连字符。
• Add-ons 有连字符。
• Home page 是两个词。

通用计算术语：

• Website 是一个词。Web page 是两个词。
• Log in 和 log out 是动词。例如：“Log in to the website.” 这同样适用于 sign in 和 sign out。不要使用“log into”或“sign into”。
• Login 和 logout 是名词（通常用作形容词）。例如：“Click the login button.”
• 使用 email 而不是 e-mail。
• CD-ROM 的复数是 CD-ROMs。

指向 mozilla.org 的链接不应包含区域设置：

• 使用 https://www.mozilla.org/ 而不是 https://www.mozilla.org/en-US/

在句子中加入链接时：

• 避免使用“点击此处”或“此处”作为链接文本。
  • 推荐： 前往您的账户设置以取消订阅。
  • 不推荐： 点击此处取消您的订阅。

大写以下项目：

• 专有名词和名称，包括品牌名称、产品名称和功能名称
• 完整句子的第一个单词
• 缩写词和首字母缩略词的字母，除非它们通常是小写的
• 编号或项目符号列表中的第一个单词
• 键盘上按键的名称
• 冒号后完整句子的第一个单词
• 标题或题目的第一个单词

Mozilla accounts：

• Mozilla accounts 中的“a”始终是小写的，除非它与其他使用标题大小写的导航项一起出现在导航项中。
• 始终使用“sign in”和“sign out”。
• 在动词形式中，使用“sign in to your account”（而不是“sign into”）以符合语法。
• 您也可以使用“Sign in with Mozilla”。
• “Sign”应始终用作动词。如果用作名词，请使用“login”。
• 使用“sign up”作为创建新账户的行动号召。

有关如何在知识库文章中引用 Mozilla accounts 的详细信息，请参阅Mozilla 账户内容规范指南。

不要使用 “i.e.” 和 “e.g.”。这些拉丁缩写会让人困惑。为清晰起见，当您想以不同方式解释某事时，请使用“in other words”或“to put it differently”代替 i.e.。当您想举例时，请使用“for instance”、“for example”或“such as”代替 e.g.。

不要在项目列表中使用牛津逗号。 例如，使用“Extensions, themes and plugins”（不带牛津逗号），而不是“Extensions, themes, and plugins”。

使用被认为普遍理解的首字母缩略词。例如：

• HTTP
• USB
• URL

出现在产品版本、错误代码、按键和按钮中的数字将不被拼写出来。

用主动语态写说明。 用主动语态和现在时写说明。主动语态和现在时简化了说明，使其更易于遵循并鼓励立即行动。例如：

“Restart Firefox to update” 而不是 “Firefox has to be restarted”。

拼写出反斜杠(\)和正斜杠(/) 用于路径和搜索，以避免混淆。

例如：“一些图像的路径名包含反斜杠 (\\)”。

键盘快捷键 大写键盘快捷键或快捷键组合的第一个字母：Ctrl + Shift + C 或 Command + Shift + C。

不要使用俚语和习语。 我们所有的文章都被翻译成多种不同的语言，所以它们会被非英语母语者阅读和翻译。俚语和习语可能含糊不清，这会使读者困惑并使翻译更加困难。

我们为许多项目提供了特殊的视觉样式，可以通过在项目周围添加适当的维基标记来实现。 有关最常见的样式，请参阅标记语言速查表。

我们有一个特殊的维基标记 – {for} – 它允许您将信息定位到特定版本的 Firefox 或特定操作系统。 例如，您可以为运行 Windows 的用户显示一组说明，为使用 macOS X 的用户显示另一组说明（有关详细信息，请参阅如何使用For语句）。