此页面为外部作者在 Experience League 上创建内容或更新现有内容提供编辑指南。 在开始之前,请确保您:
编写文档时请记住以下几点。
技术写作,尤其是软件文档,是一个专门的行业。 即使是最多产的小说家在尝试技术写作时也会感到慌张,不是因为材料复杂或技术性强,而是因为要将复杂的技术性信息简单化。要取得成功,您的内容必须在结构上保持一致、可快速浏览、可重复使用,并且在发布管道中流动时不会出现结构和语法错误。
以下部分描述了新作者必须注意的常见问题:
如果您有两个标题,但没有文本对其分隔,请添加缺少的文本(来介绍第二个主题标题)。或者,您可以移除其中一个标题。第二标题个可能是不必要的。
例如,概述以下示例没有任何用处:
此外,如果您的第二个标题恰好是概述,则可能没有必要。您的 H1 和第一段是文章主题的概念性概述。
同样,出于 SEO 目的,概述和简介等独立标题本身并无用处。请直接指明您要介绍的产品或功能。(例如:流失报告概述)
使用更多信息作为交叉引用列表(或地图)的标题。示例:
交叉引用列表指南
因为我们手动管理 TOC(目录)文件,所以这些不匹配项很容易出错。请确保您的目录条目与您的页面名称 (H1) 相匹配。另外,请确保其与痕迹导航严密相符。
目录和列表指南
在单词或短语周围添加引号,这种情况很难避免。但是,引号是用来引用话语的,几乎从不用于产品文档中。
引号使用指南
编写程序(任务内容类型)并不是我们与生俱来的天赋。构建一个可读、清晰的程序需要实践。
步骤指南
示例程序
以下是结构良好的 Adobe 登录程序:
登录到 Adobe:
Adobe.com
上,选择 Experience Cloud。对列表使用并行结构使阅读和快速浏览变得容易。列表包括目录 (TOC)、项目符号(无序列表)或编号列表。
具有并行条目的目录示例:
前面的目录是一个很好的例子,因为:
标题和描述元数据对于 Experience League 上的 SEO、内容发现和内容质量得分非常重要。
以下是标题和描述的示例:
概念文章的描述
程序/任务文章的描述
您使用的区段取决于文章的大小和范围。
概念文章的标题
程序/任务文章的标题
(请记住,管道和产品名称会自动添加到标题中。)
以下是改进内容设计、清晰度和可读性的简单方法。这些方法还有助于提高 Acrolinx 风格分数和 ExL 上的 CQI 分数。
指引 | 描述 |
---|---|
使用主动语态 | 变被动语态为主动语态 |
使用现在时 | **弱:**Campaign v8 将于 6 月发布。 **强:**Campaign v8 于 6 月发布。 对于客户来说,现在时总是更容易阅读。 |
避免使用弱的、不必要的副词 | 非常、极其、难以置信… 副词是额外的词,如果您使用强有力且精确的动词、从句和形容词,副词并不会增加重要的意义。 |
在标题和目录条目中使用强动词 | 示例: 弱: 特征创建和管理 **强:**创建和管理特征 |
使用句子大写 | 如有疑问,请勿大写。在标题中,使用句子式大写。大写专有名词和冒号后的第一个单词。在程序中,匹配您在界面中看到的大写。 |
了解这些提高清晰度的小技巧 |
|
在 VSC 中使用拼写检查器 | 在 Visual Studio Code 中安装代码拼写检查(扩展)。 |
将单击更改为转到或选择 | 单击是一个特定于设备的词汇(存在可访问性问题),其目的是离开当前操作项,前往下一个操作。以下是更改建议:
|
在 VSC 中运行 Acrolinx | Acrolinx 检查风格和语法问题,还检查 URL、术语、拼写等。可以帮助您提高清晰度并改进 Experience League 内容的翻译。 |
更多最佳实践和资源:
有关详细信息,请参阅 Microsoft® 风格指南中的 10 大写作技巧。
向您的资产(图像)添加有意义的替换文字。考虑匹配的替换文字:
Google 会考虑 SEO 结果中的替换文字。
您无需担心产品是否需要本地化或 ExL 使用的语言。但是,您可以通过在适当的地方应用以下两个(必需的)Markdown 标记来帮助提高本地化质量:
DNL
DNL 表示请勿本地化 (do not localize)。您仅将其用于带有商标的 Adobe 产品名称,所有这些名称都必须保留英文。
语法示例:Adobe Campaign
或 Workfront
DNL 不适用于文件名或 URL。
UICONTROL
UICONTROL 表示界面控件(例如 UI 中的选项、字段、选项卡、页面、选项组或功能名称)。
语法示例:Select **Project**, then select **Save**.
在本地化内容之前,您必须应用这些标签。
对于企业标识,我们通常在指南级别的产品第一次引用中包含 Adobe。基于空间考虑,您可以将 Adobe 放在标题中,但正文中的第一次引用应包括全名。某些产品,例如 Adobe Audition 和 Adobe Premiere Pro,需要在每个附属条目的第一个或最显眼的引用中使用 Adobe,因为它是合法商标名称的一部分。
文章第一段应该定义主题并描述读者可从阅读文章中学到什么。
第一段示例(概念):
受众是访客的集合(访客 ID 列表)。Adobe 的受众服务可管理将访客数据转换为受众分段的过程。因此,创建和管理受众与创建和使用区段类似,只是前者增加了一项将受众区段共享到 Experience Cloud 的功能。
第一段示例(任务):
创建客户属性源(CSV 和 FIN 文件)并上传数据。您可以在做好准备时激活数据源。在数据源激活后,可将属性数据共享到 Analytics 和 Target。
TOC.md
是您的目录。每个指南都应该有目录。
目录的编辑指南
语法指南
{#processing-rules}
。+ Processing rules {#processing-rules}
)和目录文章链接(例如 + [Article name](article.md)
)使用正确的语法。help
目录中的子目录。每个用户指南目录必须有一个目录文件。请勿嵌套用户指南。