explain

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Explainer Document Conventions

解释文档规范

Term handling

术语处理

  • Put a term list at the top of the document in table form (
    | Term | Description |
    ). Every specialised term used in the body must be defined in this list at first occurrence.
  • A term-list entry defines what the term is in one or two sentences. The functional or behavioural detail goes in the body, not in the term list.
  • Even widely recognised proper nouns (industry-standard product names, infrastructure components, etc.) get defined here. Assume the reader does not know them.
  • When defining a compound term, define the constituent words too. If the compound has three words, give all three their own entries — readers cannot be expected to infer one from another.
  • 在文档顶部以表格形式(
    | Term | Description |
    )放置术语列表。正文中使用的每个专业术语都必须在首次出现时在此列表中定义。
  • 术语列表中的条目需用一两句话定义该术语是什么。功能或行为细节应放在正文中,而非术语列表里。
  • 即便是广为人知的专有名词(行业标准产品名称、基础设施组件等)也需在此定义。假设读者不了解这些术语。
  • 定义复合术语时,也需定义其组成词汇。如果复合术语包含三个单词,需为这三个单词分别创建条目——不能假设读者可以通过其中一个推断出另一个。

Diagram conventions

图表规范

  • Use Mermaid for diagrams. Do not use ASCII art.
  • Every node label is a term that exists in the term list. Do not introduce a new term inside a diagram.
  • Do not put
    <br/>
    inside a Mermaid node. Many renderers display the literal HTML tag. If a line break is needed, separate with
    /
    or shorten the text to fit one line.
  • For diagrams with four or more nodes, or where any label is long, use
    graph TD
    (top-down).
    graph LR
    (left-right) collapses long-label graphs into an unreadable horizontal strip.
  • 使用Mermaid绘制图表,不要使用ASCII艺术图。
  • 每个节点标签必须是术语列表中已存在的术语,不得在图表中引入新术语。
  • 不要在Mermaid节点内添加
    <br/>
    。许多渲染器会显示字面HTML标签。如果需要换行,使用
    /
    分隔或缩短文本使其适配一行。
  • 对于包含四个或更多节点,或任何标签较长的图表,使用
    graph TD
    (自上而下)布局。
    graph LR
    (自左至右)布局会将长标签图表压缩成难以阅读的水平长条。

Granularity of the description

描述粒度

  • Do not gloss details with vague language. Subjects, objects, and verbs must be explicit.
  • A phrase like "A uses B to do X" must specify what A is and why A is needed for X.
  • Avoid vague verbs like "receives" or "passes". Spell out who does what to bring the state about (e.g. "receives the address" → "the platform allocates the address automatically").
  • Do not require the reader to make a leap between steps. Every step's causal connection to the next is explicit.
  • Describe the mechanism in its general form first; tie it to specific named instances afterwards as "in case X, ...". Do not anchor the whole description to a single proper-noun example.
  • 不要用模糊语言掩盖细节。主语、宾语和动词必须明确。
  • 类似“A使用B来完成X”的表述必须明确说明A是什么,以及为什么完成X需要A。
  • 避免使用“接收”或“传递”这类模糊动词。详细说明是谁执行了什么操作导致状态变化(例如,将“接收地址”改为“平台自动分配地址”)。
  • 不要要求读者自行推断步骤之间的关联。每个步骤与下一个步骤的因果关系必须明确说明。
  • 先以通用形式描述机制;之后再将其与具体实例关联,例如“在X场景下,……”。不要将整个描述局限于某个特定的专有名词示例。

Structure

结构

  1. Term list
  2. Background (why this thing is necessary, or what problem it addresses)
  3. Mechanism (how it works — includes the diagrams)
  4. Concrete steps (commands, procedures, or worked examples)
  5. Current state (where things stand today — for ongoing systems)
  1. 术语列表
  2. 背景(说明该事物的必要性,或它解决的问题)
  3. 机制(说明其工作原理——包含图表)
  4. 具体步骤(命令、流程或示例演示)
  5. 当前状态(说明当前进展——针对仍在迭代的系统)