外部投稿人的创作风格指南
此页面为外部作者在 Experience League 上创建内容或更新现有内容提供编辑指南。 在开始之前，请确保您：
风格指南
编写文档时请记住以下几点。
- 简洁明了：不要冗言赘述。简明扼要。文章主题突出。尽量少使用附注。
- 关注受众及意图：在开始编写之前，要明确适用的客户群体以及想要实现的意图。撰写文章以帮助客户达到目的。
- 使用示例：提供用来解释概念的示例。
- 整理内容：创建多个部分，以便将有关说明划分成一组更易于管理的步骤。为了让文章表述得更加清晰，可使用屏幕截图。
技术写作的最佳实践
技术写作，尤其是软件文档，是一个专门的行业。 即使是最多产的小说家在尝试技术写作时也会感到慌张，不是因为材料复杂或技术性强，而是因为要将复杂的技术性信息简单化。要取得成功，您的内容必须在结构上保持一致、可快速浏览、可重复使用，并且在发布管道中流动时不会出现结构和语法错误。
以下部分描述了新作者必须注意的常见问题：
标题不以文本分隔（双标题）
如果您有两个标题，但没有文本对其分隔，请添加缺少的文本（来介绍第二个主题标题）。或者，您可以移除其中一个标题。第二标题个可能是不必要的。
例如，概述以下示例没有任何用处：
-
此外，如果您的第二个标题恰好是概述，则可能没有必要。您的 H1 和第一段是文章主题的概念性概述。
-
同样，出于 SEO 目的，概述和简介等独立标题本身并无用处。请直接指明您要介绍的产品或功能。（例如：流失报告概述）
交叉引用标题不一致
使用更多信息作为交叉引用列表（或地图）的标题。示例：
交叉引用列表指南
- 使用项目符号列出交叉引用
- 对指南的正式名称或页面名称使用斜体（不使用链接文本时）
- 不要在本标题（或任何标题）中使用标点
- 避免在标题中使用数字
目录条目、痕迹导航和页面名称不匹配
因为我们手动管理 TOC（目录）文件，所以这些不匹配项很容易出错。请确保您的目录条目与您的页面名称 (H1) 相匹配。另外，请确保其与痕迹导航严密相符。
目录和列表指南
- 您可能需要缩短您的目录条目，而且必须确保条目与页面名称和痕迹导航明确相关。
- 痕迹导航是从标题元数据中提取的，因此它们可以不同（出于 SEO 目的）。
使用引号而非斜体
在单词或短语周围添加引号，这种情况很难避免。但是，引号是用来引用话语的，几乎从不用于产品文档中。
引号使用指南
- 通常，对于错误消息、独特或外来词等来说，斜体比引号更适合。
- 对于界面元素，使用粗体和 UICONTROL。
程序
编写程序（任务内容类型）并不是我们与生俱来的天赋。构建一个可读、清晰的程序需要实践。
步骤指南
- 程序是一系列步骤。步骤是简短的、具有编号的单句命令。
- 每个步骤以动词或目的不定式开始（引导读者了解目标，如 要保持登录状态，请启用保持登录状态）。如果某个步骤在整个过程中有特定目标，请在操作之前提及目标。
- 如果您有关于步骤的信息（一种名为步骤信息的内容类型），请将其添加到步骤之后（与步骤缩进）或资产（屏幕快照、视频、或接口描述列表）之后。
- 如果您的步骤包含两个操作（例如，选择这个，然后选择那个），请用简短句子描述。
- 将您的任务限制在大约七到十步之内。如果您在一项任务中创建十个以上的步骤，您可能需要将其分成两项任务。请在此处使用您的最佳判断。
- 在产品文档中，不要使用标题作为步骤。（以下教程除外。）
- 对于多页教程，可以允许将标题作为步骤。但是，请不要编号。相反，请拼出步骤 1：、步骤 2：等。
示例程序
以下是结构良好的 Adobe 登录程序：
登录到 Adobe：
- 在
Adobe.com上，选择 Experience Cloud。 - 选择登录。
- 选择个人帐户。
- 要保持登录状态，请选择保持登录状态。
- 输入您的姓名和密码。
- 选择登录。
并行列表
对列表使用并行结构使阅读和快速浏览变得容易。列表包括目录 (TOC)、项目符号（无序列表）或编号列表。
具有并行条目的目录示例：
前面的目录是一个很好的例子，因为：
- 概念性父条目是名词或名词短语
- 程序（任务）是主动动词（不是动名词）句子
- 所有条目都使用句子大写格式
标题和描述元数据
标题和描述元数据对于 Experience League 上的 SEO、内容发现和内容质量得分非常重要。
以下是标题和描述的示例：
概念文章的描述
- 了解 Adobe Analytics 中的区段。获取有关在工作区中配置分段面板的帮助。
- 查找有关在 Adobe Analytics 的页面浏览量报告中使用区段的帮助。
程序/任务文章的描述
- 了解如何在 Adobe Analytics 中创建区段。
- 在 Adobe Analytics 中创建区段。了解如何根据您创建的区段选择、配置和运行报告。
您使用的区段取决于文章的大小和范围。
概念文章的标题
- 页面浏览量报告中的区段
程序/任务文章的标题
- 为页面浏览量报告创建区段
（请记住，管道和产品名称会自动添加到标题中。）
提高清晰度（和 Acrolinx 分数）的方法
以下是改进内容设计、清晰度和可读性的简单方法。这些方法还有助于提高 Acrolinx 风格分数和 ExL 上的 CQI 分数。
| 指引 | 描述 |
|---|---|
| 使用主动语态 | 变被动语态为主动语态 |
| 使用现在时 | **弱：**Campaign v8 将于 6 月发布。 **强：**Campaign v8 于 6 月发布。 对于客户来说，现在时总是更容易阅读。 |
| 避免使用弱的、不必要的副词 | 非常、极其、难以置信… 副词是额外的词，如果您使用强有力且精确的动词、从句和形容词，副词并不会增加重要的意义。 |
| 在标题和目录条目中使用强动词 | 示例： 弱： 特征创建和管理 **强：**创建和管理特征 |
| 使用句子大写 | 如有疑问，请勿大写。在标题中，使用句子式大写。大写专有名词和冒号后的第一个单词。在程序中，匹配您在界面中看到的大写。 |
| 了解这些提高清晰度的小技巧 |
|
| 在 VSC 中使用拼写检查器 | 在 Visual Studio Code 中安装代码拼写检查（扩展）。 |
| 将单击更改为转到或选择 | 单击是一个特定于设备的词汇（存在可访问性问题），其目的是离开当前操作项，前往下一个操作。以下是更改建议：
|
| 在 VSC 中运行 Acrolinx | Acrolinx 检查风格和语法问题，还检查 URL、术语、拼写等。可以帮助您提高清晰度并改进 Experience League 内容的翻译。 |
更多最佳实践和资源：
- 可快速浏览的内容：帮助读者快速找到他们需要的内容，或者能够快速地判断他们是否在所需的位置。良好撰写对快速浏览有所帮助。
- 数字：在正文中，拼出从零到九的整数，并使用数字表示 10 或更大。请参阅数字。
- 像说话一样写作，表达友善，并快速切入正题。
有关详细信息，请参阅 Microsoft® 风格指南中的 10 大写作技巧。
替换文字
向您的资产（图像）添加有意义的替换文字。考虑匹配的替换文字：
- 客户可以完成的目标（任务或概念名称）
- 您显示的功能或页面
- 您显示的图标名称
Google 会考虑 SEO 结果中的替换文字。
本地化 – DNL 和 UICONTROL
您无需担心产品是否需要本地化或 ExL 使用的语言。但是，您可以通过在适当的地方应用以下两个（必需的）Markdown 标记来帮助提高本地化质量：
-
DNLDNL 表示请勿本地化 (do not localize)。您仅将其用于带有商标的 Adobe 产品名称，所有这些名称都必须保留英文。
语法示例：
Adobe Campaign或WorkfrontDNL 不适用于文件名或 URL。
-
UICONTROLUICONTROL 表示界面控件（例如 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）使用粗体文本。
- 若需进行强调或当未斜体会造成混淆时，请使用斜体。例如，外来词，或者当您描述一个词或定义一个术语时。
