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

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

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

风格指南 style-guidelines

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

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

技术写作的最佳实践 writing-tips

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

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

标题不以文本分隔(双标题) double-headings

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

例如,概述 ​以下示例没有任何用处:

双标题

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

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

交叉引用标题不一致 maps

使用​ 更多信息 ​作为交叉引用列表(或地图)的标题。示例:

交叉引用列表

交叉引用列表指南

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

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

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

目录和列表指南

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

使用引号而非斜体 quotes

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

引号使用指南

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

程序 steps

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

步骤指南

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

示例程序

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

登录到 Adobe:

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

并行列表 lists

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

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

并行目录

前面的目录是一个很好的例子,因为:

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

标题和描述元数据 metadata

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

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

概念文章的描述

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

程序/任务文章的描述

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

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

概念文章的标题

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

程序/任务文章的标题

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

(请记住,管道和产品名称会自动添加到标题中。)

提高清晰度(和 Acrolinx 分数)的方法 tips

以下是改进内容设计、清晰度和可读性的简单方法。这些方法还有助于提高 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 大写作技巧

替换文字 alt-text

向您的资产(图像)添加有意义的替换文字。考虑匹配的替换文字:

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

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

本地化 – DNL 和 UICONTROL localization

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

  • DNL

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

    语法示例:Adobe CampaignWorkfront

    DNL 不适用于文件名或 URL。

  • UICONTROL

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

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

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

在产品名称中使用 Adobe product-names

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

第一段 firstparas

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

第一段示例(概念):

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

第一段示例(任务):

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

第一段的 SEO 技巧 seo

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

大写 capitalization

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

目录 using-toc

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

目录 ​的编辑指南

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

语法指南

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

粗体和斜体 bold

  • 仅对您在程序中单击的界面元素(以及使用 UICONTROL)使用粗体文本。
  • 若需进行强调或当未斜体会造成混淆时,请使用斜体。例如,外来词,或者当您描述一个词或定义一个术语时。
recommendation-more-help
f0a0e44c-5d56-45af-ac98-47677caca18f