explain
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseExplainer Document Conventions
解释文档规范
Term handling
术语处理
- Put a term list at the top of the document in table form (). Every specialised term used in the body must be defined in this list at first occurrence.
| Term | Description | - 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 inside a Mermaid node. Many renderers display the literal HTML tag. If a line break is needed, separate with
<br/>or shorten the text to fit one line./ - For diagrams with four or more nodes, or where any label is long, use (top-down).
graph TD(left-right) collapses long-label graphs into an unreadable horizontal strip.graph LR
- 使用Mermaid绘制图表,不要使用ASCII艺术图。
- 每个节点标签必须是术语列表中已存在的术语,不得在图表中引入新术语。
- 不要在Mermaid节点内添加。许多渲染器会显示字面HTML标签。如果需要换行,使用
<br/>分隔或缩短文本使其适配一行。/ - 对于包含四个或更多节点,或任何标签较长的图表,使用(自上而下)布局。
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
结构
- Term list
- Background (why this thing is necessary, or what problem it addresses)
- Mechanism (how it works — includes the diagrams)
- Concrete steps (commands, procedures, or worked examples)
- Current state (where things stand today — for ongoing systems)
- 术语列表
- 背景(说明该事物的必要性,或它解决的问题)
- 机制(说明其工作原理——包含图表)
- 具体步骤(命令、流程或示例演示)
- 当前状态(说明当前进展——针对仍在迭代的系统)