外部投稿人的创作风格指南

此页面为外部作者在 Experience League 上创建内容或更新现有内容提供编辑指南。 在开始之前，请确保您：

  • 熟悉 Markdown 创作
  • 检查文章中的拼写和语法
  • 使用友好的语气、一致的表述和简单的句子来改进机器翻译
  • 遵循本页的最佳实践和编辑标准

风格指南

编写文档时请记住以下几点。

  • 简洁明了：不要冗言赘述。简明扼要。文章主题突出。尽量少使用附注。
  • 关注受众及意图：在开始编写之前，要明确适用的客户群体以及想要实现的意图。撰写文章以帮助客户达到目的。
  • 使用示例：提供用来解释概念的示例。
  • 整理内容：创建多个部分，以便将有关说明划分成一组更易于管理的步骤。为了让文章表述得更加清晰，可使用屏幕截图。

技术写作的最佳实践

技术写作，尤其是软件文档，是一个专门的行业。 即使是最多产的小说家在尝试技术写作时也会感到慌张，不是因为材料复杂或技术性强，而是因为要将复杂的技术性信息​简单化。要取得成功，您的内容必须在结构上保持一致、可快速浏览、可重复使用，并且在发布管道中流动时不会出现结构和语法错误。

以下部分描述了新作者必须注意的常见问题：

标题不以文本分隔（双标题）

如果您有两个标题，但没有文本对其分隔，请添加缺少的文本（来介绍第二个主题标题）。或者，您可以移除其中一个标题。第二标题个可能是不必要的。

例如，概述​以下示例没有任何用处：

双标题

  • 此外，如果您的第二个标题恰好是​概述，则可能没有必要。您的 H1 和第一段是文章主题的概念性概述。

  • 同样，出于 SEO 目的，概述​和​简介​等独立标题本身并无用处。请直接指明您要介绍的产品或功能。（例如：流失报告概述）

交叉引用标题不一致

使用​更多信息​作为交叉引用列表（或地图）的标题。示例：

交叉引用列表

交叉引用列表指南

  • 使用项目符号列出交叉引用
  • 对指南的正式名称或页面名称使用斜体（不使用链接文本时）
  • 不要在本标题（或任何标题）中使用标点
  • 避免在标题中使用数字

目录条目、痕迹导航和页面名称不匹配

因为我们手动管理 TOC（目录）文件，所以这些不匹配项很容易出错。请确保您的目录条目与您的页面名称 (H1) 相匹配。另外，请确保其与痕迹导航严密相符。

目录和列表指南

  • 您可能需要缩短您的目录条目，而且必须确保条目与页面名称和痕迹导航明确相关。
  • 痕迹导航是从标题元数据中提取的，因此它们可以不同（出于 SEO 目的）。

使用引号而非斜体

在单词或短语周围添加引号，这种情况很难避免。但是，引号是用来引用话语的，几乎从不用于产品文档中。

引号使用指南

  • 通常，对于错误消息、独特或外来词等来说，斜体比引号更适合。
  • 对于界面元素，使用粗体和 UICONTROL。

程序

编写程序（任务​内容类型）并不是我们与生俱来的天赋。构建一个可读、清晰的程序需要实践。

步骤指南

  • 程序是一系列步骤。步骤是简短的、具有编号的​单句​命令。
  • 每个步骤以动词或​目的​不定式开始（引导读者了解目标，如 要保持登录状态，请启用​保持登录状态）。如果某个步骤在整个过程中有特定目标，请在操作之前提及目标。
  • 如果您有关于步骤的信息（一种名为​步骤信息​的内容类型），请将其添加到步骤之后（与步骤缩进）或资产（屏幕快照、视频、或接口描述列表）之后。
  • 如果您的步骤包含两个操作（例如，选择这个，然后选择那个），请用简短句子描述。
  • 将您的任务限制在大约七到十步之内。如果您在一项任务中创建十个以上的步骤，您可能需要将其分成两项任务。请在此处使用您的最佳判断。
  • 在产品文档中，不要使用标题作为步骤。（以下教程除外。）
  • 对于多页教程，可以允许将标题作为步骤。但是，请不要编号。相反，请拼出​步骤 1：、步骤 2：​等。

示例程序

以下是结构良好的 Adobe 登录程序：

登录到 Adobe：

  1. 在 Adobe.com 上，选择 Experience Cloud。
  2. 选择​登录。
  3. 选择​个人帐户。
  4. 要保持登录状态，请选择​保持登录状态。
  5. 输入您的姓名和密码。
  6. 选择​登录。

并行列表

对列表使用并行结构使阅读和快速浏览变得容易。列表包括目录 (TOC)、项目符号（无序列表）或编号列表。

具有并行条目的目录示例：

并行目录

前面的目录是一个很好的例子，因为：

  • 概念性父条目是名词或名词短语
  • 程序（任务）是主动动词（不是动名词）句子
  • 所有条目都使用句子大写格式

标题和描述元数据

标题​和​描述​元数据对于 Experience League 上的 SEO、内容发现和内容质量得分非常重要。

以下是标题和描述的示例：

概念文章的描述

  • 了解 Adobe Analytics 中的区段。获取有关在工作区中配置分段面板的帮助。
  • 查找有关在 Adobe Analytics 的页面浏览量报告中使用区段的帮助。

程序/任务文章的描述

  • 了解如何在 Adobe Analytics 中创建区段。
  • 在 Adobe Analytics 中创建区段。了解如何根据您创建的区段选择、配置和运行报告。

您使用的区段取决于文章的大小和范围。

概念文章的标题

  • 页面浏览量报告中的区段

程序/任务文章的标题

  • 为页面浏览量报告创建区段

（请记住，管道和产品名称会自动添加到标题中。）

提高清晰度（和 Acrolinx 分数）的方法

以下是改进内容设计、清晰度和可读性的简单方法。这些方法还有助于提高 Acrolinx 风格分数和 ExL 上的 CQI 分数。

指引 描述
使用主动语态 变被动语态为主动语态
使用现在时 **弱：**Campaign v8 将于 6 月发布。

**强：**Campaign v8 于 6 月发布。

对于客户来说，现在时总是更容易阅读。
避免使用弱的、不必要的副词 非常、极其、难以置信…

副词是额外的词，如果您使用强有力且精确的动词、从句和形容词，副词并不会增加重要的意义。
在标题和目录条目中使用强动词 示例：

弱： 特征创建和管理

**强：**创建和管理特征
使用句子大写 如有疑问，请勿大写。在标题中，使用句子式大写。大写专有名词和冒号后的第一个单词。在程序中，匹配您在界面中看到的大写。
了解这些提高清晰度的小技巧
  • 避免使用“为了”（它没有增加任何意义）。您只需使用“要”。
  • 避免“利用”。​这听起来可能更具技术性，但事实并非如此。利用​的意思是​好好利用，尤其是那些不是为了这个目的但会提供​的东西。
  • 避免使用分号：改用句号并开始一个新句子。分号会带来不必要的复杂性。
  • 冒号：使用冒号来引入列表。在句子中谨慎使用冒号。大写句子中冒号后的第一个单词。
  • 使用牛津逗号（列表中的三个逗号）。
  • 将句子长度保持在 39 字以下。
  • 导航：使用​转到​或​导航到。
  • 除非显示路径是重要信息，否则避免使用原始 URL 文本（使用用户友好的链接文本）。
在 VSC 中使用拼写检查器 在 Visual Studio Code 中安装代码拼写检查（扩展）。
将​单击​更改为​转到​或​选择 单击​是一个特定于设备的词汇（存在可访问性问题），其目的是离开当前操作项，前往下一个操作。以下是更改建议：
  • 导航：转到文件 > 打印。
  • 单击：选择文件 > 打印​或​选择确定。
请参阅描述与 UI 的交互，了解有关在各种情况下最佳单词选择的更多原则。
在 VSC 中运行 Acrolinx Acrolinx 检查风格和语法问题，还检查 URL、术语、拼写等。可以帮助您提高清晰度并改进 Experience League 内容的翻译。

更多最佳实践和资源：

  • 可快速浏览的内容：帮助读者快速找到他们需要的内容，或者能够快速地判断他们是否在所需的位置。良好撰写对快速浏览有所帮助。
  • 数字：​在正文中，拼出从零到九的整数，并使用数字表示 10 或更大。请参阅数字。
  • 像说话一样写作，表达友善，并快速切入正题。

有关详细信息，请参阅 Microsoft® 风格指南中的 10 大写作技巧。

替换文字

向您的资产（图像）添加有意义的替换文字。考虑匹配的替换文字：

  • 客户可以完成的目标（任务或概念名称）
  • 您显示的功能或页面
  • 您显示的图标名称

Google 会考虑 SEO 结果中的替换文字。

本地化 – DNL 和 UICONTROL

您无需担心产品是否需要本地化或 ExL 使用的语言。但是，您可以通过在适当的地方应用以下两个（必需的）Markdown 标记来帮助提高本地化质量：

  • DNL

    DNL 表示​请勿本地化 (do not localize)。您仅将其用于带有商标的 Adobe 产品名称，所有这些名称都必须保留英文。

    语法示例：Adobe Campaign 或 Workfront

    DNL 不适用于文件名或 URL。

  • UICONTROL

    UICONTROL 表示界面控件（例如 UI 中的选项、字段、选项卡、页面、选项组或功能名称）。

    语法示例：Select **Project**, then select **Save**.

重要

在本地化内容之前，您必须应用这些标签。

在产品名称中使用 Adobe

对于企业标识，我们通常在指南级别的产品第一次引用中包含 Adobe。基于空间考虑，您可以将 Adobe 放在标题中，但正文中的第一次引用应包括全名。某些产品，例如 Adobe Audition 和 Adobe Premiere Pro，需要在每个附属条目的第一个或最显眼的引用中使用 Adobe，因为它是合法商标名称的一部分。

第一段

文章第一段应该定义主题并描述读者可从阅读文章中学到什么。

第一段示例（概念）：

受众是访客的集合（访客 ID 列表）。Adobe 的受众服务可管理将访客数据转换为受众分段的过程。因此，创建和管理受众与创建和使用区段类似，只是前者增加了一项将受众区段共享到 Experience Cloud 的功能。

第一段示例（任务）：

创建客户属性源（CSV 和 FIN 文件）并上传数据。您可以在做好准备时激活数据源。在数据源激活后，可将属性数据共享到 Analytics 和 Target。

第一段的 SEO 技巧

  • 在第一段中包括搜索词。
  • 使用读者使用的术语。
  • 包括同义词，如有必要，也纳入术语的先前用法。例如，“Experience Cloud ID 服务 (ECID)，以前称为​访客 ID 或缩写如 MID、MCVID，这个通用的永久 ID 可用来识别访客。“
  • 在链接中包含 SEO 术语。
  • 避免将重要术语放在复杂的表格中。复杂的表格不会产生可靠的搜索结果。系统不会搜索图片中的文字。系统会搜索字幕。

大写

  • Adobe 样式对所有标题、副标题和页面导航元素使用句子大写样式。
  • 除第一个单词和专有名词（例如品牌名称、解决方案名称和服务名称）外，所有单词均为小写。
  • 必须与工具、选项、菜单项、对话框和字段的产品名称中的大小写相符。

目录

TOC.md 是您的目录。每个指南都应该有目录。

目录​的编辑指南

  • 大写：每个条目一律使用句子大小写（不包括首字母缩略词）。只有正式的产品名称或界面元素（页面、选项卡、字段、选项等）使用大写。引用时必须与 UI 相符。
  • 动词形式和排比：使用命令式动词并避免动名词。目录是列表，因此在大多数情况下都请尽量使列表内容保持平行。有些例外情况有时是无法避免的。对于概念性页面，请使用名词和名词短语。对于任务，请使用动词。

语法指南

  • 目录中的章节标题（父）不得为链接，因其没有包含内容的页面。它应该包含一个锚点，例如 {#processing-rules}。
  • 您必须对目录章节标题（例如 + Processing rules {#processing-rules}）和目录文章链接（例如 + [Article name](article.md)）使用正确的语法。
  • 目录文章条目可以是文章标题的缩写版本。请遵循本文档中编写概述、概念和任务的标准。
  • 避免将同一文件多次添加到一个目录（或多个目录）。这样做会导致错误。
  • 如果您的存储库中包含多个用户指南，则您的用户指南目录必须处于同一级别，例如 help 目录中的子目录。每个用户指南目录必须有一个目录文件。请勿嵌套用户指南。

粗体和斜体

  • 仅对您在程序中单击的界面元素（以及使用 UICONTROL）使用粗体文本。
  • 若需进行强调或当未斜体会造成混淆时，请使用斜体。例如，外来词，或者当您描述一个词或定义一个术语时。

在此页面上