写作指南

使用以下写作指南来创建清晰一致的产品内容，并体现 Cloudflare 的品牌声音和产品语气。我们使用的语气根据用户在使用某些产品和功能时的目标而有所不同。我们强调产品内的易用性。

通俗易懂的语言是指受众在首次阅读时就能够理解并根据其采取行动的文字。使用通俗易懂的语言可以确保受众理解您的意思。Cloudflare 用户是一个全球性的受众群体，他们的第一语言可能不是英语。通俗易懂的语言使翻译更容易，并使文档更具可访问性。

在写作中，请考虑以下关于使用通俗易懂语言的建议：

• 将重要信息放在开头。
• 避免使用晦涩难懂的词汇。
• 使用简单的句子。一个句子应该只表达一个想法。
• 避免使用缩写。
• 保持一致。

有关通俗易懂语言的更多信息，请参阅通俗语言指南系列 ↗。

将您的内容中心围绕客户的目标，而不是 Cloudflare 的业务目标。写作时先写目标，再写操作。

使提供的信息与用户旅程中的特定阶段相关。确保对提供的任何指标进行定义或给出更多上下文。

不要在功能描述中列出性能统计数据。

使用自信且清晰的语气，防止客户产生疑虑。以专业知识为基础进行引导，切勿居高临下地对待受众。

主要答案或核心说明应始终出现在主要内容流中，而不应仅存在于选项卡或可折叠区域内。

只有在阐述了通用概念之后，才能针对特定平台的变化（例如，仪表板对比 API 对比 Terraform）使用选项卡。使用 Details 提供补充信息，而不是用于主要答案。

在引入技术概念时，从基础开始，逐步过渡到更高级的主题。在说明“如何做”之前，先解释“为什么”。

在不使用行业黑话的情况下交流概念。如果可能，将其替换。定义缩写词和技术术语。参考下表，了解如何将行业黑话翻译为通俗易懂语言的示例：

请考虑以下几点，以帮助您在写作中避免行业黑话：

• 考虑您受众的知识水平。
• 考虑用户是否需要了解该术语才能完成任务或理解文档。

主动语态比被动语态更简洁直接，应尽可能使用。使信息对使用 Cloudflare 产品的任何人来说都清晰易懂。宁可选择清晰，也不要追求极简的文案。

使用现在时动词。尽可能避免使用过去时，因为这会很快使内容显得过时或无关紧要。将来时应仅用于尚未发生的动作。

专注于解决问题。预测客户的问题，在写作时将解决方案牢记于心，并将其嵌入到界面中。

创建对残障人士友好的产品内容。可访问性确保所有用户都能有效地获取、理解和使用 Cloudflare 文档。

关键的可访问性实践包括：

• 提供具有信息量、独特的页面标题。
• 使用 headings 来传达意义和结构。
• 让链接文本具有实际意义。
• 为图像编写有意义的替代文本（alt 文本）。
• 为多媒体创建转录本和字幕。
• 提供清晰的指令。
• 保持内容清晰简洁。

有关与 WCAG 2.1 标准一致的全面可访问性指南，请参阅可访问性指南页面。

使用简单的语言和格式，视上下文而定。尊重用户的时间。

• 将句子控制在 8 到 12 个单词之间。
• 使用简短、清晰的句子和段落进行写作。
• 避免使用不必要的复杂词汇和短语。
• 首次使用时展开缩写词。例如，Web 内容可访问性指南（WCAG）。
• 考虑为读者可能不知道的术语提供术语表。
• 视情况使用列表格式。
• 考虑使用图像、插图、视频和符号来帮助澄清含义，或者在书面描述不够直观时使用。

每个带有 pcx_content_type 的页面在其 frontmatter 中都必须包含一个 description。该描述会填充 <meta name="description"> 标签，搜索引擎和 AI 系统利用该标签来决定是否呈现或引用某个页面。

将与正文内容相同的通俗语言原则应用于描述中：

• 编写 1-2 个自成一体的句子。
• 命名产品或功能。
• 说明该页面如何帮助读者操作或理解。
• 编写描述时，使其在从页面中提取出来时能够作为独立的回答片段发挥作用。

不要使用通用的开篇句：

有关详细指南和示例，请参阅编写描述。

在整篇文档中始终一致地使用相同的明确词汇或术语。

分词是以 -ed 或 -ing 结尾并起修饰作用的动词。动名词是以 -ing 结尾并起名词作用的动词。这两类词都很有用且可以接受，但如果它们在句子中放置不当，可能会引起混淆。例如，单词 meeting（会议/会面）可以是一个动名词或分词（甚至是一个名词），这取决于它在句子中的位置。当您使用动名词和分词时，请确保意思清晰。

最后一个示例说明了悬空修饰语。在“避免做法”示例中，using 没有主语，因此隐含的主语是 address（地址），这是不正确的。如果隐含的主语不正确，您必须修改句子，为修饰短语提供一个主语。

教程或高级流程文章或主题的标题通常以动名词开头。标题的上下文比句子少，因此您必须特别小心，确保意思清晰。

Cloudflare 拥有全球客户群。为了包容我们的所有客户并使国际化过程更顺畅，对于需要翻译的内容，请考虑以下指南。除了我们所有的一般产品写作指南外，请使用以下指南确保您所写的内容有利于本地化。

• 表达清晰：不清晰的信息很难翻译，甚至无法翻译。如果用英语表达不清晰，用任何其他语言也不会清晰。
• 避免文化参考：特定的文化参考只对您写作时所处的地区或我们的一小部分客户有意义，因此不要在产品或文档中使用它们。
• 不要使用缩写：即使存在空间限制，也不要使用缩写。它们是英语特有的，很难翻译。
• 提供定义和上下文信息：切勿在未定义的情况下使用技术术语或缩写词。对于无法翻译的术语，信息和上下文至关重要。

在写作文档时要将包容性和多样性牢记于心。以下是一些通用指南和示例，展示了应遵循的一些最佳实践。

我们用来描述和讨论我们的产品、功能和流程的语言很重要。无论我们是在撰写博客文章、主持网络研讨会还是策划营销活动，我们的目标始终是创建能与我们全球、多元化受众产生共鸣的包容性内容。我们不使用涉及种族歧视、性别歧视或排他性（体能歧视）的术语。

除了下面列出的指南外，我们还识别并替换了几个行业相关术语，这些术语对于来自某些背景、文化和/或信仰的人来说可能会产生冒犯或痛苦。

不要使用根源于种族主义的术语。我们不使用将好的结果和操作描述为 "white"（白），而将坏的操作或结果描述为 "black"（黑）的术语（例如 whitehat/blackhat hacker，白帽/黑客黑客），也不使用源自描述奴隶制语言的常见行业术语（例如 master/slave，主/从）。

将带有性别色彩的术语替换为无性别色彩的术语。当指代已知代词的特定人员时，可以使用带性别色彩的语言。在讨论产品和技术流程时，这是没有必要的——例如，将假设的攻击者称为 "he"（他）或将硬件设备称为 "she"（她）。

避免使用针对残障人士的排他性术语和隐喻。这不仅适用于行业术语，也适用于像 "crazy"（疯狂）和 "insane"（荒谬）这样的描述词，这些词会强化负面的体能歧视刻板印象。

在编写或编辑时，识别一些可能对部分或全部受众来说不熟悉的术语。当您发现此类术语时，请采取以下策略之一：

• 如果该术语已经存在，请链接到一个现有的良好说明。
• 如果您的文档正在引入该术语，请定义该术语。

具有口语化、节省空间且易于扫描的词汇，对于非英语母语者来说通常更容易阅读。长词或长短语对于传达特定含义可能是必要的，但应谨慎使用。

为了在网络上进行有效的交流，您需要遵循网页标准，为阅读而设计，并将印刷材料重新用于网络。有关网页标准的更多信息，请参阅通俗语言指南系列 ↗。

包含真实生活用例的简短示例。用这些示例来支持正在讨论的核心观点。在添加这些示例时要目标明确且审慎——每个示例都必须服务于清晰的目的并为读者增加价值。