Back to Details

adev-writing-guide

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Angular Documentation (adev) Writing Guide

Angular文档（adev）写作指南

This skill provides comprehensive guidelines for authoring content in 
adev/src/content
. It combines Google's technical writing standards with Angular-specific markdown conventions, components, and best practices.
本指南为编写
adev/src/content
中的内容提供了全面规范，结合了Google技术写作标准与Angular专属的Markdown约定、组件及最佳实践。

I. Google Technical Writing Guidelines

I. Google技术写作准则

Tone and Content

语气与内容

  • Be conversational and friendly: Maintain a helpful yet professional tone. Avoid being overly casual.
  • Write accessibly: Ensure documentation is understandable to a diverse global audience, including non-native English speakers.
  • Audience-first: Focus on what the user needs to do, not just what the system does.
  • Avoid pre-announcing: Do not mention unreleased features or make unsupported claims.
  • Use descriptive link text: Link text should clearly indicate the destination (e.g., avoid "click here").
  • 保持对话式且友好： 维持实用且专业的语气，避免过于随意。
  • 具备易读性： 确保文档能被全球不同受众理解，包括非英语母语使用者。
  • 以受众为中心： 聚焦用户需要完成的操作，而非仅介绍系统功能。
  • 避免提前预告： 勿提及未发布功能或作出无依据的声明。
  • 使用描述性链接文本： 链接文本应清晰指向目标内容（例如，避免使用“点击此处”）。

Language and Grammar

语言与语法

  • Use second person ("you"): Address the reader directly.
  • Prefer active voice: Clearly state who or what is performing the action (e.g., "The system generates a token" vs "A token is generated").
  • Standard American English: Use standard American spelling and punctuation.
  • Conditional clauses first: Place "if" or "when" clauses before the instruction (e.g., "If you encounter an error, check the logs").
  • Define terms: Introduce new or unfamiliar terms/acronyms upon first use.
  • Consistent terminology: Use the same term for the same concept throughout the document.
  • Conciseness: Aim for one idea per sentence. Keep sentences short.
  • 使用第二人称（“你”）： 直接与读者对话。
  • 优先使用主动语态： 明确说明动作的执行者（例如，“系统生成令牌”而非“令牌被生成”）。
  • 标准美式英语： 使用标准美式拼写与标点。
  • 条件从句前置： 将“if”或“when”引导的从句放在指令之前（例如，“如果你遇到错误，请检查日志”）。
  • 定义术语： 在首次使用新术语或缩写时进行解释。
  • 术语一致性： 同一概念在文档中始终使用相同术语。
  • 简洁性： 每句表达一个核心观点，尽量缩短句子长度。

Formatting and Organization

格式与结构

  • Sentence case for headings: Capitalize only the first word and proper nouns in titles and headings.
  • Lists:
    • Numbered lists: Use for sequential steps or prioritized items.
    • Bulleted lists: Use for unordered collections of items.
    • Description lists: Use for term-definition pairs.
  • Serial commas: Use the Oxford comma (comma before the last item in a list of three or more).
  • Code formatting: Use code font for code-related text (filenames, variables, commands).
  • UI Elements: formatting user interface elements in bold.
  • Date formatting: Use unambiguous formats (e.g., "September 4, 2024" rather than "9/4/2024").
  • Structure: Use logical hierarchy with clear introductions and navigation. Headings should be task-based where possible.
  • 标题采用句首大写： 标题中仅首单词和专有名词大写。
  • 列表：
    • 编号列表： 用于顺序步骤或优先级项目。
    • 项目符号列表： 用于无顺序的项目集合。
    • 描述列表： 用于术语-定义配对。
  • 牛津逗号： 在三个及以上项目的列表中，最后一个项目前使用逗号。
  • 代码格式： 代码相关文本（文件名、变量、命令）使用代码字体。
  • UI元素： 用户界面元素使用粗体格式。
  • 日期格式： 使用无歧义的格式（例如，“2024年9月4日”而非“9/4/2024”）。
  • 结构： 采用逻辑层级，包含清晰的引言与导航。标题应尽可能以任务为导向。

Images and Code Samples

图片与代码示例

  • Images: Use simple, clear illustrations to enhance understanding.
  • Captions: Write captions that support the image.
  • Code Samples:
    • Ensure code is correct and builds without errors.
    • Follow language-specific conventions.
    • Comments: Focus on why, not what. Avoid commenting on obvious code.
  • 图片： 使用简洁清晰的插图提升理解效果。
  • 图片说明： 撰写辅助图片理解的说明文字。
  • 代码示例：
    • 确保代码正确且可无错误构建。
    • 遵循语言专属约定。
    • 注释： 聚焦于“为什么”而非“是什么”，避免对明显代码添加注释。

Reference Hierarchy

参考层级

  1. Project-specific style guidelines (if any exist in 
    CONTRIBUTING.md
    or similar).
  2. Google Developer Documentation Style Guide.
  3. Merriam-Webster (spelling).
  4. Chicago Manual of Style (non-technical).
  5. Microsoft Writing Style Guide (technical).
  1. 项目专属风格指南（若存在于
    CONTRIBUTING.md
    或类似文件中）。
  2. Google开发者文档风格指南。
  3. 韦氏词典（拼写参考）。
  4. 芝加哥手册（非技术内容参考）。
  5. Microsoft写作风格指南（技术内容参考）。

II. Angular Documentation Specifics

II. Angular文档专属规范

Code Blocks

代码块

Use the appropriate language identifier for syntax highlighting:
  • TypeScript (Angular): Use 
    angular-ts
    when TypeScript code examples contain inline templates.
  • HTML (Angular): Use 
    angular-html
    for Angular templates.
  • TypeScript (Generic): Use 
    ts
    for plain TypeScript.
  • HTML (Generic): Use 
    html
    for plain HTML.
  • Shell/Terminal: Use 
    shell
    or 
    bash
    .
  • Mermaid Diagrams: Use 
    mermaid
    .
使用合适的语言标识符实现语法高亮：
  • TypeScript (Angular)： 当TypeScript代码示例包含内联模板时，使用
    angular-ts
    。
  • HTML (Angular)： 对于Angular模板，使用
    angular-html
    。
  • TypeScript (通用)： 纯TypeScript代码使用
    ts
    。
  • HTML (通用)： 纯HTML代码使用
    html
    。
  • Shell/终端： 使用
    shell
    或
    bash
    。
  • Mermaid图表： 使用
    mermaid
    。

Attributes

属性

You can enhance code blocks with attributes in curly braces 
{}
after the language identifier:
  • header="Title"
    : Adds a title to the code block.
  • linenums
    : Enables line numbering.
  • highlight="[1, 3-5]"
    : Highlights specific lines.
  • hideCopy
    : Hides the copy button.
  • prefer
    : Marks code as a preferred example (green border/check).
  • avoid
    : Marks code as an example to avoid (red border/cross).
Example:
markdown
```angular-ts {header:"My Component", linenums, highlight="[2]"}
@Component({
  selector: 'my-app',
  template: '<h1>Hello</h1>',
})
export class App {}
```
你可以在语言标识符后的大括号
{}
中添加属性来增强代码块功能：
  • header="Title"
    ：为代码块添加标题。
  • linenums
    ：启用行号显示。
  • highlight="[1, 3-5]"
    ：高亮指定行。
  • hideCopy
    ：隐藏复制按钮。
  • prefer
    ：标记代码为推荐示例（绿色边框/对勾）。
  • avoid
    ：标记代码为需避免的示例（红色边框/叉号）。
示例：
markdown
```angular-ts {header:"My Component", linenums, highlight="[2]"}
@Component({
  selector: 'my-app',
  template: '<h1>Hello</h1>',
})
export class App {}
```

<docs-code>
Component

<docs-code>
组件

For more advanced code block features, use the 
<docs-code>
component:
  • path
    : Path to a source file (e.g., 
    adev/src/content/examples/...
    ).
  • header
    : Custom header text.
  • language
    : Language identifier (e.g., 
    angular-ts
    ).
  • linenums
    : Boolean attribute.
  • highlight
    : Array of line numbers/ranges (e.g., 
    [[3,7], 9]
    ).
  • diff
    : Path to diff file.
  • visibleLines
    : Range of lines to show initially (collapsible).
  • region
    : Region to extract from source file.
  • preview
    : Boolean. Renders a live preview (StackBlitz). Only works with standalone examples.
  • hideCode
    : Boolean. Collapses code by default.
Multifile Example:
html
<docs-code-multifile path="..." preview>
  <docs-code path="..." />
  <docs-code path="..." />
</docs-code-multifile>
如需更高级的代码块功能，可使用
<docs-code>
组件：
  • path
    ：源文件路径（例如，
    adev/src/content/examples/...
    ）。
  • header
    ：自定义标题文本。
  • language
    ：语言标识符（例如，
    angular-ts
    ）。
  • linenums
    ：布尔属性。
  • highlight
    ：行号/行范围数组（例如，
    [[3,7], 9]
    ）。
  • diff
    ：差异文件路径。
  • visibleLines
    ：初始显示的行范围（可折叠）。
  • region
    ：从源文件中提取的代码区域。
  • preview
    ：布尔值，渲染实时预览（StackBlitz）。仅适用于独立示例。
  • hideCode
    ：布尔值，默认折叠代码。
多文件示例：
html
<docs-code-multifile path="..." preview>
  <docs-code path="..." />
  <docs-code path="..." />
</docs-code-multifile>

Alerts / Admonitions

提示框/警示框

Use specific keywords followed by a colon for alerts. These render as styled blocks.
  • NOTE:
    For ancillary information.
  • TIP:
    For helpful hints or shortcuts.
  • IMPORTANT:
    For crucial information.
  • CRITICAL:
    For warnings about potential data loss or severe issues.
  • TODO
    : For incomplete documentation.
  • QUESTION:
    To pose a question to the reader.
  • SUMMARY:
    For section summaries.
  • TLDR:
    For concise summaries.
  • HELPFUL:
    For best practices.
Example:
markdown
TIP: Use `ng serve` to run your application locally.
使用特定关键字加冒号来创建提示框，这些提示框会渲染为样式化区块：
  • NOTE:
    用于辅助信息。
  • TIP:
    用于实用提示或快捷方式。
  • IMPORTANT:
    用于关键信息。
  • CRITICAL:
    用于关于潜在数据丢失或严重问题的警告。
  • TODO
    : 用于未完成的文档内容。
  • QUESTION:
    用于向读者提出问题。
  • SUMMARY:
    用于章节摘要。
  • TLDR:
    用于简洁摘要。
  • HELPFUL:
    用于最佳实践内容。
示例：
markdown
TIP: Use `ng serve` to run your application locally.

Custom Components

自定义组件

  • Cards (
    <docs-card>
    ):
    • Must be inside 
      <docs-card-container>
      .
    • Attributes: 
      title
      , 
      link
      , 
      href
      .
  • Callouts (
    <docs-callout>
    ):
    • Attributes: 
      title
      , 
      important
      , 
      critical
      .
  • Pills (
    <docs-pill>
    ):
    • Must be inside 
      <docs-pill-row>
      .
    • Attributes: 
      title
      , 
      href
      .
  • Steps / Workflow (
    <docs-step>
    ):
    • Must be inside 
      <docs-workflow>
      .
    • Attributes: 
      title
      .
  • Tabs (
    <docs-tab>
    ):
    • Must be inside 
      <docs-tab-group>
      .
    • Attributes: 
      label
      .
  • Videos (
    <docs-video>
    ):
    • Attributes: 
      src
      (YouTube embed URL), 
      alt
      .
  • 卡片 (
    <docs-card>
    )：
    • 必须放置在
      <docs-card-container>
      内。
    • 属性：
      title
      , 
      link
      , 
      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嵌入链接）, 
      alt
      。

Images

图片

Use standard markdown syntax with optional attributes for sizing and loading behavior.
  • #small
    , 
    #medium
    : Append to image URL for sizing.
  • {loading: 'lazy'}
    : Add attribute for lazy loading.
Example:
markdown
![Alt Text](path/to/image.png#medium {loading: 'lazy'})
使用标准Markdown语法，可添加可选属性调整尺寸和加载行为：
  • #small
    , 
    #medium
    ：追加到图片URL后调整尺寸。
  • {loading: 'lazy'}
    ：添加属性启用懒加载。
示例：
markdown
![Alt Text](path/to/image.png#medium {loading: 'lazy'})

Headers

标题

  • Use markdown headers (
    #
    , 
    ##
    , 
    ###
    ).
  • Ensure a logical hierarchy (don't skip levels).
  • h2
    and 
    h3
    are most common for content structure.
  • 使用Markdown标题（
    #
    , 
    ##
    , 
    ###
    ）。
  • 确保逻辑层级清晰（不要跳过层级）。
  • h2
    和
    h3
    是内容结构中最常用的层级。