technical-writing

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Technical writing

技术写作

Overview

概述

House style for technical documents, written in English and composed from conventions used across my repositories. Documents keep their own language: a Dutch document is written and reviewed in Dutch. The structural and truth rules apply in any language; the vocabulary lists in

references/style.md

are English-specific and other languages carry their own. Core principle: a document states current, verified behavior, conclusion first, with every claim traceable to a source, and every fact living in exactly one place. A thin document beats an overstated one, because the author is the one saying it out loud.

These rules govern documents, not chat replies. Length and section rules apply to running prose, not to reference lists like this file.

技术文档的内部统一写作风格，基于我所有代码库通用的约定制定，以英文撰写。文档保留自身语言：荷兰语文档需用荷兰语撰写和审核。结构与事实规则适用于所有语言；

references/style.md

中的词汇列表仅针对英文，其他语言有各自对应的词汇表。核心原则：文档应先阐述结论，说明当前已验证的行为，所有主张均可追溯到来源，且每个事实仅存在于一处。 简洁的文档优于夸大其词的文档，因为作者要为内容负责。

这些规则仅适用于文档，不适用于聊天回复。篇幅和章节规则适用于连贯的文稿，不适用于本文这类参考列表。

When to invoke

调用场景

Load this skill for any technical prose, then the matching document-type skill on top. These are routing hints; each skill's own body is the authority.

The task is	Also load
A proposal, RFC, design doc, spec, or migration plan	`writing-design-docs`
Recording a decision, an ADR, a decision log entry	`recording-decisions`
A changelog entry, release notes, "what shipped"	`writing-changelogs`
A runbook, setup guide, procedure, troubleshooting entry	`writing-runbooks`
A tracker item: epic, story, task, bug report, spike, acceptance criteria	`writing-issues`
A migration or deprecation guide	`writing-runbooks`
A postmortem, incident report, root-cause analysis	`writing-postmortems`
Reviewing or rewriting someone else's text; the final pass before delivering any document	`reviewing-technical-prose`

撰写任何技术文稿时加载本技能，再叠加匹配的文档类型技能。以下是路由提示，各技能的正文内容为权威依据。

任务类型	还需加载的技能
提案、RFC、设计文档、规格说明或迁移计划	`writing-design-docs`
记录决策、ADR、决策日志条目	`recording-decisions`
更新日志条目、发布说明、“已交付内容”	`writing-changelogs`
运行手册、安装指南、操作流程、故障排查条目	`writing-runbooks`
跟踪项：史诗、用户故事、任务、Bug报告、研究任务、验收标准	`writing-issues`
迁移或弃用指南	`writing-runbooks`
事后分析、事件报告、根本原因分析	`writing-postmortems`
审核或改写他人文稿；交付前的最终检查	`reviewing-technical-prose`

What this skill does not do

本技能不涵盖的内容

It does not govern marketing copy, social posts, or UI microcopy; only the truth rules in
```
references/truth.md
```
still bind those.
It does not decide content: what is true comes from the sources, not from the style.
It does not license restyling existing documents that follow their own conventions; apply the precedence rules below.
A request to make a document "punchy", "compelling", or "persuasive" does not override it: the numbers persuade, the register stays plain.

不规范营销文案、社交帖子或UI微文案；仅
```
references/truth.md
```
中的事实规则对这些内容仍有约束力。
不决定内容：事实来自来源，而非写作风格。
不允许改写遵循自身约定的现有文档；需遵循下文的规则优先级。
要求文档“有力”“吸引人”或“有说服力”的请求不能凌驾于本规则之上：数据才有说服力，行文需保持平实。

Mandatory checkpoint before drafting

起草前的强制检查点

Before drafting a new document or substantial section, derive and state in working notes:

Kind: <normative|descriptive|historical|runbook|reference> | Audience: <who> | Purpose: <the verb the reader must accomplish> | Non-goals: <what this deliberately does not cover>

Fill the fields from the request, sources, and repository context. State a safe assumption and continue when it does not materially change the result. Ask only when an unknown would change the audience, substance, or scope. Never invent a fact to complete the checkpoint, and do not insert the checkpoint into the finished document unless its schema requires it.

在起草新文档或重要章节前，需在工作笔记中明确以下内容：

类型: <规范性|描述性|历史性|运行手册|参考性> | 受众: <目标人群> | 目的: <读者需完成的动作> | 非目标: <本文档明确不涵盖的内容>

根据需求、来源和代码库上下文填写字段。若未知信息不会对结果产生实质性影响，可做出合理假设并继续。仅当未知信息会改变受众、内容或范围时才需询问。切勿编造事实来完成检查点，除非文档架构要求，否则不要将检查点插入最终文档。

Read first, then write

先阅读，再写作

The most important step and the one most often skipped. Before writing a line:

Read up to two comparable documents in the same directory. Adopt their structure, tone, and conventions. When fewer than two comparable documents exist, read every available example and then use repository-level conventions. Do not block because the directory is new.
Check for a
```
README.md
```
that indexes the documents. If it exists, add the new document to it.
Check whether the topic already lives somewhere. Extending the owner is almost always better than starting a rival document beside it.

这是最重要却常被跳过的步骤。动笔前：

阅读同一目录下最多两篇同类文档，采用它们的结构、语气和约定。若同类文档不足两篇，则阅读所有可用示例，再遵循代码库层面的约定。不要因目录是新建的而停滞。
检查是否存在索引文档的
```
README.md
```
。若存在，将新文档添加到其中。
检查主题是否已存在于其他地方。扩展现有文档几乎总是优于在旁边新建一份竞争文档。

Rule precedence

规则优先级

When instructions conflict, apply them in this order:

Truth, safety, and historical-integrity rules.
An explicit exception in the active document-type skill.
The shared hard rules below.
An explicit schema and the conventions in the target directory.
Shared style preferences in
```
references/style.md
```
.

Existing practice controls only choices that a higher rule does not settle. It cannot weaken sourcing, rewrite accepted history, or represent unverified work as shipped. A document-type exception must name the rule it bends and the boundary of the exception.

An author's explicit, stated style choice outranks the shared style preferences and nothing else: when the author says leave my voice alone, the style pass stops, while truth, safety, and history stay binding whoever objects.

当指令冲突时，按以下顺序应用：

事实、安全和历史完整性规则。
对应文档类型技能中的明确例外。
下文的通用硬性规则。
目标目录中的明确架构和约定。
```
references/style.md
```
中的通用风格偏好。

现有惯例仅适用于更高优先级规则未明确的选择。它不能削弱来源要求、改写已被接受的历史，或把未验证的工作描述为已交付。文档类型例外必须指明其调整的规则及例外边界。

作者明确陈述的风格选择优先于通用风格偏好，但仅此而已：当作者要求保留其行文风格时，风格检查需停止，但事实、安全和历史规则无论谁反对都仍具约束力。

Classify the document before editing it

编辑前先分类文档

The edit rule differs per kind. "Update docs to match code" is actively wrong for two of the five.

Kind	Examples	Edit rule
Normative	architecture principles, contracts, style guides	If code violates the contract, do NOT water the contract down; record the violation. Edit only when the contract itself names deleted or renamed concepts.
Descriptive	flows, component docs, state machines	Update to match code exactly. Verify against implementations, not names.
Historical	changelogs, old specs, decision logs, applied migrations	Never rewrite history. Flag discrepancies; supersede with a new entry.
Runbook	operations, troubleshooting, release procedures	Update to match reality; every step must have been actually run.
Reference	API docs, config references, indexes	Exhaustive: every key, every flag, with defaults and a Usage column.

If an entire document describes something deleted, do not delete the file: mark it obsolete with a one-line banner ("> NOTE: describes removed component X; see Y") and leave the removal to the owner.

不同类型的文档，编辑规则不同。“更新文档以匹配代码”对五种类型中的两种是错误操作。

类型	示例	编辑规则
规范性	架构原则、契约、风格指南	若代码违反契约，切勿弱化契约；需记录违规情况。仅当契约本身提及已删除或重命名的概念时才进行编辑。
描述性	流程、组件文档、状态机	严格更新以匹配代码。需对照实现验证，而非名称。
历史性	更新日志、旧规格说明、决策日志、已完成的迁移记录	切勿改写历史。标记不一致之处；通过新增条目替代旧内容。
运行手册	操作流程、故障排查、发布步骤	更新以匹配实际情况；每一步都必须已实际执行过。
参考性	API文档、配置参考、索引	内容需详尽：每个键、每个标志都需包含默认值和“用法”列。

若整个文档描述的内容已被删除，请勿删除文件：用一行横幅标记为过时（"> 注意：本文档描述已移除的组件X；请参阅Y"），并将删除操作交由文档所有者处理。

Hard rules

硬性规则

Non-negotiable, in every document:

No em dashes, no en dashes, no
--
dashes. Use commas, colons, semicolons, periods, parentheses, or
```
-
```
with spaces as an aside marker. A plain hyphen serves ranges (
```
2026-2030
```
). Check all four forms before delivery.
No changelog section and no "last updated" field inside a document. Git history is the history. This holds per sentence too: describe current behavior, never the previous behavior ("this step replaced the manual check" belongs in a migration doc or release note, not in a procedure).
No delivery history as narrative status in prose, comments, names, or strings: no phases, task IDs, ticket keys, SHAs, or plan references that merely describe how work was delivered. A pinned commit may appear solely as claim evidence. Ticket keys may appear as functional metadata in tracker records, commit messages, planning documents, and citations; never in code comments or user-facing content.
Never state as fact what you cannot trace to code at a cited path, a pinned commit, a test, a document, or a primary source. A plausible guess presented as fact is worse than "the source says nothing about this." See
```
references/truth.md
```
.
One fact, one home. Everything else links to the owner. A summary may route, never decide: when an index and its source disagree, the source wins and the index is the bug.
Accepted decisions and applied migrations are immutable. Corrections are new dated entries, never edits to history.
Headings in sentence case, never Title Case.

所有文档都必须遵守，无协商余地：

禁止使用长破折号、短破折号或
--
。使用逗号、冒号、分号、句号、括号，或带空格的
```
-
```
作为旁注标记。普通连字符用于表示范围（
```
2026-2030
```
）。交付前需检查这四种形式。
文档内部禁止包含更新日志章节或“最后更新”字段。Git历史即为记录。此规则同样适用于每一句话：描述当前行为，切勿提及之前的行为（“此步骤替代了手动检查”属于迁移文档或发布说明的内容，而非操作流程）。
禁止在文稿、注释、名称或字符串中提及交付历史作为叙事状态：禁止出现阶段、任务ID、工单编号、SHA值或仅描述工作交付方式的计划引用。固定提交仅可作为主张证据出现。工单编号可作为功能性元数据出现在跟踪记录、提交信息、规划文档和引用中；切勿出现在代码注释或面向用户的内容中。
切勿将无法追溯的内容陈述为事实，需可追溯到指定路径的代码、固定提交、测试、文档或原始来源。将合理猜测当作事实比“来源未提及此内容”更糟糕。详见
```
references/truth.md
```
。
一个事实，一个归属地。其他所有内容都需链接到归属文档。摘要仅可引导，不可定义：当索引与其来源不一致时，以来源为准，索引存在错误。
已被接受的决策和已完成的迁移不可更改。更正内容需添加新的带日期条目，切勿编辑历史。
标题采用句首大写格式，切勿采用标题大小写格式。

Workflow

工作流程

Read first (above), and classify the document.
Declare before drafting: audience, purpose, scope, and what the document deliberately does not cover. Infer these from the request and repository, state safe assumptions, and ask only when an unknown would materially change the result.
Draft conclusion-first at every level: document, chapter, paragraph. No run-up, no context paragraphs before the outcome. Each chapter opens with what came out of it, not how it was approached.
Ground every claim and label its confidence:
```
references/truth.md
```
.
Style pass over sentences, words, headings, and the banned-constructions list:
```
references/style.md
```
.
Verify before delivery: load
```
reviewing-technical-prose
```
for the checklist. Check references by actually following them.

先阅读（见上文），并对文档进行分类。
起草前明确：受众、目的、范围以及文档明确不涵盖的内容。根据需求和代码库推导，做出合理假设，仅当未知信息会对结果产生实质性影响时才需询问。
结论先行：在文档、章节、段落等各个层面都先给出结论。不要铺垫，不要在结果前写背景段落。每个章节都以最终产出开头，而非阐述过程。
为所有主张提供依据并标注可信度：
```
references/truth.md
```
。
风格检查：检查句子、词汇、标题以及禁用表达列表：
```
references/style.md
```
。
交付前验证：加载
```
reviewing-technical-prose
```
技能执行检查清单。通过实际访问链接来验证参考内容。

Audience

受众

The same subject needs a different cut per reader. Know who you write for before starting. Not "users": the actual person, where they are, and the verb they must accomplish.

Reader	What they need
Developers	The why behind the choice, and what changes about their work tomorrow
Tech leads / architects	Trade-offs, alternatives, long-term consequences
Management / PO	What it yields, what it costs, which risks
External parties	No internal team names or jargon without explanation

Writing for several groups at once: the summary reads for the broadest group, the rest may deepen. If a phrase would need a footnote, it needs rewriting rather than a footnote.

同一主题针对不同读者需采用不同表述方式。动笔前需明确目标读者。不是泛指“用户”，而是具体的人、所处场景以及他们需要完成的动作。

读者	需求
开发人员	选择背后的原因，以及对他们未来工作的影响
技术主管/架构师	权衡取舍、替代方案、长期影响
管理层/产品负责人	产出、成本、风险
外部人员	若无解释，禁止提及内部团队名称或行话

同时面向多个群体写作：摘要面向最广泛的群体，其余部分可深入展开。若某个表述需要脚注，则需重写而非添加脚注。

Common mistakes

常见错误

Starting at the solution. First the problem, then the proposal.
Documenting what the code already shows. Documents own reasoning, constraints, invariants, and alternatives; the code owns the what.
Unverifiable claims: "faster", "better" without a number or source. Add the number or cut the claim.
Filling a gap with a plausible guess instead of naming the gap.
Vague owners: "this still needs investigation" without a name or role.
Listing only benefits. Every proposal names its costs.
Silently trimming, reordering for emphasis, or restyling a host document during an edit pass. Edits are surgical: preserve voice, structure, numbering, and IDs.
A document that grows past roughly 800 lines of prose while nobody looks: split it and let the main document point.

从解决方案开始写。应先写问题，再提提案。
记录代码已展示的内容。文档负责阐述理由、约束、不变量和替代方案；代码负责展示具体实现。
无法验证的主张：无数据或来源的“更快”“更好”。需补充数据或删除该主张。
用合理猜测填补空白，而非明确说明空白。
模糊的负责人：“此内容仍需调研”却未指明具体人名或角色。
仅列出优势。每个提案都需说明其成本。
编辑时悄悄删减、重新排序以强调重点，或更改宿主文档的风格。编辑需精准：保留原文语气、结构、编号和ID。
文档在无人关注的情况下增长到约800行文稿：需拆分文档，让主文档作为索引指向子文档。