docs-style-guide

文档风格指南执行器

编写或审查产品文档和教程时，应用并执行写作风格指南。完整指南随此技能一同打包，位于 ./reference/ 下。应用或引用规则前，请先阅读相关文件，并以这些文件为准。

切勿引用、注明或链接本次会话中尚未加载的规则，也切勿编造规则、“应该／不应该”示例或参考路径。如果尚未阅读相关文件，请先阅读，否则不要提及。

目的

统一的写作风格和语气能让品牌更鲜明、更有活力。风格指南体现了以下目标：

• 优先考虑非英语母语者。
• 优先考虑疲惫的运维人员。
• 优先考虑内容作者。
• 优先考虑多种产品。

指导原则

• 切勿使用隐喻、明喻或其他修辞手法，即使你经常在印刷品中看到它们。
• 能用短词时，切勿用长词。
• 只要可以删掉一个词，就一定删掉。
• 可以使用主动语态时，切勿使用被动语态。
• 能想到日常英语表达时，切勿使用外语短语、科学术语或行话。
• 如果遵守任何指南弊大于利，就打破这条规则。

内容范围

应用指南前，请检查规则中的 内容集 字段，确认它适用于你正在处理的内容。列表包含以下一种或多种内容类型：

• documentation — 介绍现有功能的产品参考文档和概念文档。
• tutorials — 通过一系列任务引导读者达成特定目标的分步学习内容。

撰写或审查前，请确定适用的内容集。如果内容兼具两种内容集的特点，例如概念页面末尾附有引导式操作步骤，请对符合相应内容集的部分分别应用相应规则。如果无法判断内容所属类别，默认采用 documentation 规则，并咨询技术文档撰写人员。不要将规则应用于其未列出的内容集。

工作流程

1. 确定内容集（documentation 或 tutorials），明确待审查内容的类别。
2. 选择相关指南。 根据下方的参考索引，选取适用于待审查内容的主题文件。
3. 阅读规则文件后再应用或引用规则，确保指南和示例准确。
4. 应用规则或报告问题。
   • 撰写内容时，遵循适用规则。
   • 审查内容时，针对每项违规指出具体规则、规则文件链接，以及指南提供的 应该/不应该 修正方式或示例。
5. 遵循每条规则的内容集范围，跳过未列出当前内容集的规则。

确认

如果只是审查，请直接报告违规问题，无需暂停。编辑现有文件前，请先确认预期的修改范围，并询问判断所需的背景信息（例如内容集），不要擅自猜测。

参考索引

• 通用写作指南（./reference/general/）：
  • active-voice.md — 主动语态
  • content-organization.md — 内容组织
  • fonts-and-formats.md — 字体和格式
  • grammar.md — 语法和标点
  • language.md — 语言和用词
  • links.md — 链接
  • point-of-view.md — 视角
  • tense-and-time.md — 时态和时间
  • titles-and-headings.md — 标题和章节标题
• 代码块和控制台（./reference/codeblocks-and-consoles/）：
  • organization.md — 内容组织
  • fonts-and-formats.md — 字体和格式
  • language.md — 语言和用词
• reference/ui-components.md — UI 组件。
• 数字、日期和时间（./reference/numbers-dates-time/）：
  • dates-and-time.md — 日期和时间
  • format-numbers.md — 数字格式
  • words-as-numbers.md — 数字的文字表达
• Markdown 规范（./reference/markdown/）：
  • fonts-and-formats.md — 字体和格式
  • headings.md — 标题

反模式

• 将规则应用于其未列出的内容集。
• 引用或转述尚未加载的规则。
• 在主动语态适用时使用被动语态。
• 明明可以使用简单词语，却使用冗长的词语、外语短语或术语。