adev-writing-guide

Angular 文档（adev）写作指南

本指南为在 adev/src/content 中撰写内容提供全面指导，结合了 Google 技术写作标准与 Angular 特有的 Markdown 约定、组件和最佳实践。

I. Google 技术写作指南

语气和内容

• 亲切友好地交流： 保持乐于助人且专业的语气。避免过于随意。
• 确保易于理解： 确保不同背景的全球读者（包括非英语母语者）都能理解文档。
• 以读者为先： 关注用户需要执行的操作，而不只是系统的功能。
• 避免提前公布： 不要提及尚未发布的功能，也不要做出没有依据的声明。
• 使用描述性链接文本： 链接文本应清楚说明链接的目标（例如，避免使用“点击此处”）。

语言和语法

• 使用第二人称（“you”）： 直接面向读者。
• 优先使用主动语态： 清楚说明由谁或什么执行操作（例如，“系统会生成令牌”，而非“令牌会被生成”）。
• 使用标准美式英语： 遵循标准美式拼写和标点。
• 将条件从句置于句首： 将“if”或“when”从句放在指令之前（例如，“如果遇到错误，请检查日志”）。
• 定义术语： 首次使用时介绍新术语或不熟悉的术语／缩略语。
• 术语保持一致： 同一概念在全文中使用同一术语。
• 简洁明了： 每句话尽量只表达一个观点，句子要简短。

格式和组织

• 标题使用句首字母大写格式： 标题中只将首词和专有名词的首字母大写。
• 列表：
  • 编号列表： 用于表示按顺序执行的步骤或有优先级的项目。
  • 项目符号列表： 用于表示无序项目集合。
  • 定义列表： 用于表示术语与定义的配对。
• 使用系列逗号： 列出三个或更多项目时，在最后一项之前加逗号（Oxford comma）。
• 代码格式： 文件名、变量、命令等与代码相关的文本使用代码字体。
• UI 元素： 用户界面元素使用粗体格式。
• 日期格式： 使用明确无歧义的格式（例如，“September 4, 2024”，而不是“9/4/2024”）。
• 结构： 采用清晰的逻辑层次，提供明确的介绍和导航。尽可能使用以任务为导向的标题。

图片和代码示例

• 图片： 使用简单明了的插图来帮助理解。
• 说明文字： 编写能补充图片内容的说明文字。
• 代码示例：
  • 确保代码正确且能够无错误地构建。
  • 遵循特定语言的约定。
  • 注释： 重点说明 原因，而不是 内容。避免注释显而易见的代码。

参考资料层级

1. 项目专属的风格指南（如果 CONTRIBUTING.md 或类似文件中有相关内容）。
2. Google 开发者文档风格指南。
3. Merriam-Webster（拼写）。
4. 芝加哥格式手册（非技术内容）。
5. Microsoft 写作风格指南（技术内容）。

---

II. Angular 文档特定要求

代码块

使用合适的语言标识符进行语法高亮：

• TypeScript（Angular）： TypeScript 代码示例包含内联模板时，使用 angular-ts。
• HTML（Angular）： Angular 模板使用 angular-html。
• TypeScript（通用）： 纯 TypeScript 使用 ts。
• HTML（通用）： 纯 HTML 使用 html。
• Shell／终端： 使用 shell 或 bash。
• Mermaid 图表： 使用 mermaid 围栏代码块。<docs-code language="mermaid"> 不受支持，会导致构建失败。

属性

可以在语言标识符后使用花括号 {} 中的属性来增强代码块。header 和 highlight 后面需要带冒号和值；其余属性是独立标志。将标志写成 flag: true 会导致构建失败，并报错 Invalid code block metadata；使用无法识别的键也会导致相同错误：

• header: "Title"：为代码块添加标题。
• linenums：启用行号。
• highlight: [2]：高亮指定行。递增的两个数字组成一个范围，因此 [12, 19] 会高亮第 12 行到第 19 行。一个数字或三个及以上数字表示字面列表。嵌套一层即可混合使用这两种形式：[[3,7], 9]。
• hideCopy：隐藏复制按钮。
• hideDollar：在 shell 示例中隐藏 $ 提示符。
• prefer：将代码标记为首选示例（绿色边框／勾号）。
• avoid：将代码标记为应避免的示例（红色边框／叉号）。

示例：

```angular-ts {header: "My Component", linenums, highlight: [2]}
@Component({
  selector: 'my-app',
  template: '<h1>Hello</h1>',
})
export class App {}
```

<docs-code> 组件

如需更高级的代码块功能，请使用 <docs-code> 组件。其属性采用 HTML 语法：使用双引号的 attr="value"，布尔属性则只写名称。组件不会进行验证，因此无法识别的属性和单引号括起来的值都会被忽略，且不会报错：

• path：源文件路径（例如 adev/src/content/examples/...）。
• header：自定义标题文本。
• language：语言标识符（例如 angular-ts）。省略时会根据文件扩展名推断；如果扩展名无法识别，则默认使用 angular-ts。因此，对于 shell、markdown 和 scss 文件，请设置此属性。
• linenums：布尔属性。
• highlight：行号／范围数组，语义与围栏代码块形式相同（例如 [[3,7], 9]）。
• visibleLines：初始显示的行范围（可折叠）。
• region：从源文件中提取的区域。
• preview：布尔值。在代码下方将示例渲染为运行中的组件。仅适用于独立示例。
• hideCode：布尔值。默认折叠代码。
• hideDollar：在 shell 示例中隐藏 $ 提示符。
• prefer / avoid：将示例标记为首选示例或应避免的示例。

多文件示例：

<docs-code-multifile path="..." preview>
  <docs-code path="..." />
  <docs-code path="..." />
</docs-code-multifile>

警示／提示框

使用特定关键词并在后面加冒号来显示警示。这些内容会渲染为带样式的区块。

• NOTE: 用于补充信息。
• TIP: 用于实用提示或快捷方式。
• IMPORTANT: 用于重要信息。
• CRITICAL: 用于可能导致数据丢失或严重问题的警告。
• TODO: 用于未完成的文档内容。
• QUESTION: 用于向读者提出问题。
• SUMMARY: 用于总结章节内容。
• TLDR: 用于简要概述。
• HELPFUL: 用于最佳实践。

示例：

TIP: Use `ng serve` to run your application locally.

自定义组件

• 卡片（<docs-card>）：
  • 通常放在 <docs-card-container> 中；单张卡片也可以单独渲染。
  • 属性：title、href、link、imgSrc、iconImgSrc、titleInline。
  • href 是目标地址，link 只会替换默认的“了解详情”标签，因此写在 link 中的 URL 会作为文本显示；没有 href 的卡片不可点击。
• 提示框（<docs-callout>）：
  • 属性：title、important、critical。
• 标签（<docs-pill>）：
  • 必须放在 <docs-pill-row> 中。
  • 属性：title、href。
• 步骤／工作流（<docs-step>）：
  • 必须放在 <docs-workflow> 中。
  • 属性：title。
• 选项卡（<docs-tab>）：
  • 必须放在 <docs-tab-group> 中。
  • 属性：label。
• 视频（<docs-video>）：
  • 属性：src（YouTube 嵌入 URL）、title（在播放链接标签中显示的视频名称）。

图片

使用标准 Markdown 语法，并可添加用于调整尺寸和加载行为的属性。

• #small、#medium：追加到图片 URL 后，用于调整尺寸。
• {loading: 'lazy'}：添加延迟加载属性。

示例：

![Alt Text](path/to/image.png#medium {loading: 'lazy'})

标题

• 使用 Markdown 标题（#、##、###）。
• 确保层级合理（不要跳过级别）。
• 内容结构中最常用的是 h2 和 h3。