make-the-docs-trustworthy

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Make the Docs Trustworthy

让文档可信

Core principle. A reader must be able to act on this page without checking it against the system first.

A second copy of a fact destroys that. The two disagree in the end, and neither one announces itself as the stale one.
The weight sits in Search before you write. Everything after it is what to do once the search has answered.
You opened this in the middle of something. This is how to do that work, not a replacement for it. Name what you were doing before you start, and return to it when this is done.

核心原则：读者无需先对照系统，就能依据此页面采取行动。

事实的重复记录会破坏可信度：最终两者会出现不一致，且没有任何一方会表明自己已过时。
关键在于“写作前先搜索”：搜索之后的所有步骤都是基于搜索结果的后续操作。
你是在某个工作过程中打开此指南的：这是完成该工作的方法，而非替代原有工作。开始前先说明你正在做的事情，完成后再回到原有工作。

Search before you write

写作前先搜索

You MUST look for the fact first. Where it already exists, edit it there.
A second copy adds no source. It adds a sentence that will disagree with the first one.
The reader cannot tell which of the two is current. That is the whole cost, and it lands on someone else.
Where something already prints the fact, write the pointer and stop. A manifest, a config file, a generated block, a command's own help.

必须先查找事实的现有记录：如果已存在，就在原位置编辑。
重复记录无法增加可信度：只会添加一句与原记录可能产生矛盾的内容。
读者无法区分两者哪个是最新的：这就是全部代价，且会由他人承担。
如果已有内容能输出该事实（如清单、配置文件、生成块、命令自身的帮助信息），只需写入指向该内容的链接即可，无需重复记录。

Write only what cannot be found by looking

仅记录无法通过查找获取的内容

Keep the convention nobody wrote down.
Keep the reason a thing is the way it is.
Keep the trap that has caught people.
Drop whatever one command or one file already answers. That is restatement, and restatement is stale the moment it is written.

保留未被书面记录的约定。
保留事物当前状态的原因。
保留曾让人们踩坑的陷阱。
删除任何单个命令或文件已能回答的内容：这属于重复表述，从写下的那一刻起就已经过时。

Which rules to read

应遵循哪些规则

This table is a gate, not a checklist. Match the left column against what you are about to write, correct, or remove.

One rule per row. The match sets where to start.
The change class sets what is permitted. Name it before the edit.
Run the search this gate demands before any rule. It can make the write unnecessary.
Read both rows where a claim matches two. Reading is the cheap half. Writing the wrong thing is the expensive half.
Supersede where a rule would delete a decision record.

If you see...	Read
a fact about to be written down, or one that already appears in two places and they disagree	`rules/one-place-for-a-fact.md`
prose describing what a manifest, configuration, generated block, or command's own help already states	`rules/restatement-is-drift.md`
a claim that something is out of date, with no change to anchor it to	`rules/staleness-without-a-diff.md`
a file that has absorbed content beyond the job its name implies, or that nobody can describe in one line	`rules/one-artifact-one-job.md`
a document being cited as a reason, which no human is known to have read	`rules/unreviewed-prose.md`
a constraint invisible in the code, a deliberate deviation, or an alternative readers keep re-proposing	`rules/record-what-code-cannot-show.md`
a recorded decision whose answer has changed, or a page whose subject no longer exists	`rules/supersede-or-delete.md`
no established location, numbering, or heading scheme for what you are about to add	`rules/match-the-existing-shape.md`

Discriminators.

One-place against restatement. Split by what the duplicate is. Another piece of prose, against an artifact that renders the fact already.
Staleness against one-artifact. Split by symptom. A sentence that is untrue, against a file whose job cannot be stated.
Record against supersede. Split by moment. The first time it is written, against every time after.

Default stance.

Search for the fact before writing it, and edit it where it already lives.
Write only what cannot be found by looking. Anything a command already prints becomes a pointer.
Say what you chose not to write, so the omission is a decision rather than a gap.

此表格是筛选入口，而非检查清单：对照左列内容，判断你将要撰写、修正或移除的内容类型。

每行对应一条规则：匹配结果决定你从哪里开始。
变更类别决定允许的操作：编辑前先明确类别。
在遵循任何规则前，先按此入口要求完成搜索：这可能让写作变得不必要。
如果一项内容匹配两行，则需阅读对应的两条规则：阅读成本很低，但写错内容的代价很高。
若规则要求删除决策记录，则采用替代方案。

当你遇到...	阅读对应规则
即将被记录的事实，或是已在两处出现且内容不一致的事实	`rules/one-place-for-a-fact.md`
描述清单、配置、生成块或命令自身帮助信息已包含内容的文字	`rules/restatement-is-drift.md`
声称内容过时，但没有对应的变更记录作为依据	`rules/staleness-without-a-diff.md`
文件内容超出其名称所暗示的用途，或是无人能用一句话描述其用途	`rules/one-artifact-one-job.md`
被作为依据引用，但已知无人阅读过的文档	`rules/unreviewed-prose.md`
代码中不可见的约束、刻意的偏离，或是读者不断提出的替代方案	`rules/record-what-code-cannot-show.md`
已记录的决策答案发生变更，或是页面主题已不存在	`rules/supersede-or-delete.md`
你要添加的内容没有既定的存放位置、编号或标题格式	`rules/match-the-existing-shape.md`

区分说明：

单位置规则 vs 重复表述规则：根据重复内容的类型区分。是另一篇文字，还是已能呈现事实的工件。
过时规则 vs 单工件规则：根据症状区分。是表述不实的句子，还是用途无法明确的文件。
记录规则 vs 替代规则：根据时间节点区分。是首次记录，还是后续的变更。

默认准则：

写作前先搜索事实，并在其已有位置进行编辑。
仅记录无法通过查找获取的内容：任何命令已能输出的内容都只需添加指向它的链接。
说明你选择不记录的内容：让省略成为主动决策，而非遗漏。

Prose nobody has read is not a source

无人阅读的文字不能作为可靠来源

Do one of two things before citing a document as your reason. Re-derive its claim from the system, or say plainly that you did not.
You SHOULD re-derive rather than disclaim where the claim decides anything. Disclaiming is the honest option, not the cheap one.
You MAY take either one. The silent third option is the one that costs.
That silence turns one wrong sentence into a convention.
Agent-written prose piles up fastest and gets trusted first. That is backwards.

在引用某文档作为依据前，需完成以下两项操作之一：从系统中重新验证其主张，或明确说明你未进行验证。
当主张会影响决策时，应优先重新验证而非免责声明：免责声明是诚实的选择，但并非低成本选项。
你可以选择任意一种方式：但沉默不言的第三种选项会带来代价。
沉默会将一个错误表述变成约定俗成的内容。
Agent生成的文字累积最快，却最先被信任：这是本末倒置的。

Settle the claim against the running system

对照运行中的系统验证主张

This skill runs when nothing points at what changed. Someone says the docs are wrong, and there is no diff to anchor it to.
Settle each claim yourself. Run the command the page describes. Open the path it names.
Check the identifier is still exported. Follow the link and see where it lands.
Report it confirmed or refuted, and name the thing that settled it.
Judging docs inside a change is a review's job. There a diff supplies the anchor, and findings are reported rather than applied.

当没有任何内容指向变更点时，适用此技能：有人说文档有误，但没有对应的变更记录作为依据。
自行验证每项主张：运行页面描述的命令，打开它指定的路径。
检查标识符是否仍被导出：点击链接查看跳转位置。
报告验证结果（确认或推翻），并说明验证所依据的内容。
评审变更中的文档评判是评审环节的工作：此时变更记录提供了依据，只需报告发现而非直接修改。

Name the change you are making

明确你所做的变更类型

Class	When	What it requires
correct	the prose says something untrue now	cite what makes it untrue
add	the fact has no home yet	the search above decides where
supersede	a recorded decision changed	the old record stays, with a pointer forward
relocate	the fact is in the wrong file	leave no surviving copy behind
delete	the subject itself is gone	never for a decision record

Deleting a page whose subject was removed is correct. It is part of the removal.
Deleting a record because its answer changed is not. It destroys the evidence that the old answer was once right.
The next reader then argues it again from nothing.
Propose any deletion, and any new file, with what depends on them named. Correcting and relocating need no proposal.

类别	适用场景	要求
修正	文字表述与当前事实不符	引用导致表述不实的依据
添加	事实尚无记录位置	上述搜索步骤决定存放位置
替代	已记录的决策发生变更	保留旧记录，并添加指向新记录的链接
迁移	事实存放在错误的文件中	不得留下任何残留副本
删除	主题本身已不存在	绝不能用于决策记录

删除主题已被移除的页面是正确操作：这属于移除工作的一部分。
因答案变更而删除记录则不正确：这会销毁“旧答案曾是正确的”这一证据。
后续读者会再次从零开始争论该问题。
任何删除操作或新文件提议都需明确列出受其影响的内容：修正和迁移无需提议。

Keep the verbatim set through any rewrite

重写时保留原文的关键内容

A rewrite, a compression, or a move preserves these exactly. Code, paths, identifiers, commands, error strings, numbers, versions, and frontmatter.
Frontmatter is the one that fails quietly. A model told to preserve it rewrites it anyway.
Lift it out before the change and put it back after.
Check the result against the original. Never trust that the instruction worked.

重写、压缩或迁移时，需完全保留以下内容：代码、路径、标识符、命令、错误字符串、数字、版本和前置元数据（frontmatter）。
前置元数据（frontmatter）最容易被悄悄修改：即使要求保留，模型仍可能对其进行重写。
在变更前将其提取出来，变更后再放回。
对照原文检查结果：永远不要相信指令会自动生效。

What to produce

输出格式示例

Claim        "the setup guide is wrong"
Resolution   refuted for steps 1-3: ran them, they work.
             confirmed for step 4: it names a flag the command's own
             help no longer lists.
Changes      correct   <setup page>:22, replace the flag with a pointer
                       to the command's help
             delete    <old setup page>: its subject was removed here
Left alone   <troubleshooting page>: every command in it still runs
Not written  the retry default: the config command already prints it
Unreviewed   none

One instance, not the set. What generalises is the shape.
Every claim gets a verdict, and every change gets a class.
What you chose not to write is said out loud.

Claim        "the setup guide is wrong"
Resolution   refuted for steps 1-3: ran them, they work.
             confirmed for step 4: it names a flag the command's own
             help no longer lists.
Changes      correct   <setup page>:22, replace the flag with a pointer
                       to the command's help
             delete    <old setup page>: its subject was removed here
Left alone   <troubleshooting page>: every command in it still runs
Not written  the retry default: the config command already prints it
Unreviewed   none

示例为单个实例，而非完整集合：通用的是格式框架。
每项主张都要有结论，每项变更都要明确类别。
明确说明你选择不记录的内容。

Do not skip this when

以下情况不得跳过此流程

The fact seems new. That is what every duplicated fact seemed like once.
The page is small. A small page is read whole and believed whole.
You are only fixing a typo. That is when the surrounding claim goes unchecked.
Nobody asked. Prose nobody checked is what the next session will cite.

事实看似是新内容：所有重复记录的事实最初都看似是新内容。
页面篇幅短小：短小的页面会被完整阅读并全盘信任。
你只是修正拼写错误：此时很容易忽略对周边内容的检查。
无人要求你这么做：未经检查的文字会成为下一次会话的引用依据。

Routing

流程指引

The table above selects the rule. Read it in full, and say which one you opened, in one line.
Whether a decision is worth recording at all is settled by the change-review rules, not here. This skill owns writing it, placing it, and keeping it true.
A direct instruction from the user outranks anything here.

上述表格用于选择对应的规则：完整阅读该规则，并用一句话说明你选择的规则。
决策是否值得记录由变更评审规则决定，而非此技能：此技能负责决策的记录、存放和维护其真实性。
用户的直接指令优先级高于此指南中的任何内容。