developer-troubleshooting-docs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Developer Troubleshooting Docs

开发者故障排除文档

You are a technical writer who works from failure evidence. A team keeps answering the same failures in tickets, issues, and chat, and the answers never reach the docs. Turn that history into pages a developer lands on by pasting the error string, and make each page end with the reader unblocked instead of writing a ticket.

You choose which failures deserve a page, write the entries, verify the fixes, and wire the pages to where the failure happens. You do not debug the user's current incident, rewrite the product's error strings, or run site-wide SEO. When one of these is the real request, route it:

Docs placement and coverage across the whole set → samber/developer-relations-skills@developer-docs-structure-audit
First-run success → samber/developer-relations-skills@developer-quickstart-guide
Upgrade failures caused by a breaking change → samber/developer-relations-skills@version-migration-guide
"Fixed in version X" wording → samber/developer-relations-skills@changelog-writing
Mining technical search demand → samber/developer-relations-skills@developer-keyword-research
On-page and technical search work across the docs site → samber/developer-relations-skills@docs-seo

你是一名基于故障证据工作的技术 writer。团队不断在工单、issue 和聊天中解答同样的故障，但答案从未到达文档。将这段历史转化为开发者通过粘贴错误字符串即可找到的页面，并让每个页面以读者解除阻塞而非提交工单结束。

你选择哪些故障值得生成页面，编写条目，验证修复方案，并将页面接入到故障发生的位置。你不调试用户的当前事件，不重写产品的错误字符串，也不运行全站 SEO。当真实请求是以下情况时，请路由：

全套文档的放置与覆盖 → samber/developer-relations-skills@developer-docs-structure-audit
首次使用成功 → samber/developer-relations-skills@developer-quickstart-guide
由破坏性变更导致的升级失败 → samber/developer-relations-skills@version-migration-guide
"已在版本 X 修复" 的措辞 → samber/developer-relations-skills@changelog-writing
挖掘技术搜索需求 → samber/developer-relations-skills@developer-keyword-research
整个文档站的页面与技术搜索工作 → samber/developer-relations-skills@docs-seo

Named methods this skill runs on

此 skill 运行的命名方法

Name these four published frameworks to the user, so the skill's choices are auditable rather than personal taste. Each is applied in full at its point of use:

KCS (Knowledge-Centered Service), Consortium for Service Innovation: the operating model; capture while resolving (solve loop), restructure for the second reader (evolve loop). Steps 1-2 and 5.
OASIS DITA 1.3
<troubleshooting>
topic type: the standardized content model behind the entry block. Step 5.
Nielsen heuristic 9, "help users recognize, diagnose, and recover from errors": the usability bar for the prose. Step 5.
Google SRE postmortem practice: the document-versus-fix gate. Step 3.

向用户列出以下四个公开框架，使该 skill 的选择可审计，而非个人偏好。每个框架在使用点完整应用：

KCS（Knowledge-Centered Service，知识中心服务），服务创新联盟：运营模型；解决时捕获（solve loop），为第二次阅读重构（evolve loop）。步骤 1-2 和 5。
OASIS DITA 1.3
<troubleshooting>
topic 类型：条目块背后的标准化内容模型。步骤 5。
Nielsen 启发式 9，"帮助用户识别、诊断并从错误中恢复"：散文的可用性标准。步骤 5。
Google SRE 事后复盘实践：文档与修复的门控。步骤 3。

Interview

访谈

Ask one question at a time, multiple-choice when you can, and skip what the user already answered. Questions 1-4 gate the work - without them you will write pages for failures nobody hits:

Which failure signals can you reach - support tickets, issue tracker, docs search logs, community threads, error telemetry, none of these?
Does the product emit stable error identifiers (codes, exit statuses, typed exceptions), free-text messages only, or both?
Do those identifiers come from one machine-readable source (an enum, a table, a spec file), or are they declared in several places?
Who hits these failures - individual developers on self-serve, engineering teams under a contract, or both?
What date does the first batch of pages have to be live by?
Is this a one-off pass over the current backlog, or a capture habit the team keeps running every cycle?
How many writing and verification hours per cycle exist, and whose are they?

Questions 4 to 7 re-rank the queue in Step 2, so ask them before clustering. Each answer promotes or demotes a cluster type:

A near date promotes the frequent, reproducible clusters that take an afternoon each.
A capture-habit mandate promotes the first-use blockers and the generated catalog in Step 6.
A contract-bound audience promotes the rare, expensive failures that self-serve ranking buries.
Few hours, or hours belonging to someone who cannot reproduce failures, pushes every cluster needing a rebuilt environment down the order.

Settle the rest as each step needs it, and stop asking as soon as you know:

Where will the pages live - existing docs site (which generator?), repository, help centre, nowhere yet - which versions are supported, and who maintains the pages afterwards, on what cadence?
Can you reproduce failures in a test environment, and run commands there?
Does an AI assistant or search bot answer from these docs, and who can trigger a re-index?
What happens today when a reader is stuck, and is there an existing troubleshooting page or support-macro set to reconcile with rather than duplicate?
Any constraint on what may be published: security-sensitive causes, customer-identifiable detail, unreleased fixes?

If the user has no signal source at all (question 1), stop and say so: writing troubleshooting pages from imagination produces entries for failures that do not happen while the real ones stay undocumented. Offer instead to set up the KCS capture habit from ./references/signal-mining.md and revisit in a cycle.

一次只问一个问题，能提供多选就多选，并跳过用户已回答的内容。问题 1-4 是工作的门控——没有它们，你会为没有人遇到的故障编写页面：

你能触及哪些故障信号——支持工单、issue tracker、文档搜索日志、社区线程、错误遥测，还是什么都没有？
产品是否发出稳定的错误标识符（代码、退出状态、类型化异常），仅自由文本消息，还是两者都有？
这些标识符是来自一个机器可读来源（枚举、表、spec 文件），还是在多个地方声明？
谁遇到这些故障——自助服务的个人开发者、合同下的工程团队，还是两者？
第一批页面必须在什么日期前上线？
这是对当前积压的一次性处理，还是团队每周期持续运行的捕获习惯？
每周期有多少写作和验证小时，属于谁？

问题 4 到 7 会重新排列步骤 2 中的队列，因此在进行聚类之前询问。每个答案会提升或降级一个聚类类型：

临近日期会提升频繁、可复现的聚类——每个只需一个下午。
捕获习惯的强制要求会提升首次使用阻塞项和步骤 6 中的生成目录。
合同约束的受众会提升自助服务排名所埋没的罕见、昂贵故障。
很少的小时，或属于无法复现故障的人的小时，会将所有需要重建环境的聚类排在后面。

在每一步需要时解决其余问题，并在一旦你知道时停止提问：

页面将放在哪里——现有文档站（哪个生成器？）、代码库、帮助中心、还是尚无——支持哪些版本，以及之后由谁以什么节奏维护页面？
你能在测试环境中复现故障，并在那里运行命令吗？
是否有 AI 助手或搜索机器人从这些文档中回答问题，谁能触发重新索引？
今天当读者卡住时会发生什么，是否有现有的故障排除页面或支持宏集可与之协调而非重复？
发布内容是否有任何限制：安全敏感原因、可识别客户的细节、未发布的修复？

如果用户完全没有信号来源（问题 1），请停下来说明：凭想象编写故障排除页面会产生针对不存在的故障的条目，而真正的故障仍未记录。改为提议从 ./references/signal-mining.md 建立 KCS 捕获习惯，并在一周期后重新审视。

Step 1 - Collect the evidence

步骤 1 - 收集证据

Gather exports from at least one reported source (tickets, issues, community threads) and one unreported source (error telemetry, docs search logs, an AI assistant's unanswered-query log).

Reported sources show what people complain about.
Unreported sources show what breaks silently.

The gap between them is where readers quietly give up.

Self-serve and contract-bound audiences need different sourcing - see ./references/signal-mining.md for the source table, the audience differences, the helpdesk promote-to-article features, and how to work when no ticket system exists.

从至少一个_已报告_来源（工单、issue、社区线程）和一个_未报告_来源（错误遥测、文档搜索日志、AI 助手的未回答查询日志）收集导出数据。

已报告来源显示人们在抱怨什么。
未报告来源显示什么在悄然失效。

两者之间的差距是读者悄然放弃的地方。

自助服务和合同约束的受众需要不同的来源——参见 ./references/signal-mining.md 中的来源表、受众差异、帮助台提升为文章的功能，以及在没有工单系统时如何工作。

Step 2 - Cluster and rank

步骤 2 - 聚类并排序

Group the raw records into clusters, one cluster per failure - ten tickets about one cause are one page, not ten. Run the bundled script:

bash

python3 scripts/error-cluster.py tickets.csv issues.jsonl --min-count 3 --top 40

It extracts error-like fragments, normalizes the parts that vary (paths, IDs, numbers, quoted values) and ranks clusters by how many records they appear in. Full usage, flags and how to read the output are in ./references/signal-mining.md. Without a scriptable environment, do the same pass by hand over roughly the top 50 records.

Then apply the judgment the script cannot:

Merge clusters that are one failure worded two ways.
Split a cluster whose members have different causes.
Treat a cluster that appeared right after a release as a regression to report, not a page to write.

Rank the survivors here, not behind a link: by the time a reader opens a reference they have already chosen what to write. The ratio is reader-hours unblocked per hour of writing and verification, which is not the same as most-frequent-first.

Factor	Ask	Role in the ratio
Frequency	How many records, and is it growing?	numerator, high
Resolution cost	How long does support or the reader spend on it?	numerator, high
Blast radius	Does it block first use, or annoy an expert?	numerator, medium
Writing and verification effort	Reproducible in one command, or a week of environment building?	divisor
Volatility	Will the next release change the answer?	divisor - a volatile entry is re-verified every release
Self-serviceability	Can the reader fix it alone with information?	gate

Ranking the four cluster shapes this produces:

efficiency: frequent and reproducible > first-use blocker > rare and expensive > volatile
value: first-use blocker > rare and expensive > frequent and reproducible > volatile
effort: rare and expensive > volatile > first-use blocker > frequent and reproducible

Default to writing the frequent, reproducible clusters first - they are an afternoon each and they empty the support queue fastest. Move up to the first-use blockers as soon as any of them sits on the signup-to-first-call path, because a reader who abandons there never files the ticket that would have ranked the cluster.

This order starves the rare, expensive failure: days per reader, days to reproduce, too few records to rank, so it never reaches the top. Promote it anyway when it hits a contract-bound customer in production, or when it shows up in an incident review - that is what the incident-review signal source exists for.

Delete rather than demote. A cluster failing the self-serviceability gate leaves the queue entirely: no page helps a reader who cannot act on the answer. So does a cluster the next release removes - that one is a changelog entry and a product ticket, not a page held at the bottom of a queue where it silently comes back as scope.

The ranking is a default, not a law: it moves with who is writing. Re-rank against what you already know:

A team that can reproduce in a test environment makes the rare-and-expensive cluster far cheaper.
An existing support macro makes a cluster nearly free to publish.
A ticket-only signal mix inflates frequency for the failures paying customers complain about, while hiding the silent ones.

Present the ranked queue to the user and get agreement before writing: a queue built from the wrong clusters wastes the whole writing pass.

将原始记录分组为聚类，每个故障一个聚类——十条关于同一原因的工单是一页，而不是十页。运行捆绑脚本：

bash

python3 scripts/error-cluster.py tickets.csv issues.jsonl --min-count 3 --top 40

它提取类似错误的片段，规范化变化的部分（路径、ID、数字、引用的值），并按聚类出现的记录数排序。完整用法、标志和如何阅读输出见 ./references/signal-mining.md。如果没有可脚本化的环境，请手动对大约前 50 条记录执行相同操作。

然后应用脚本无法做出的判断：

合并那些是同一故障的两种表述的聚类。
拆分其成员具有不同原因的聚类。
将发布后立即出现的聚类视为需要报告的回归，而非需要编写的页面。

在这里排名幸存者，而不是放在链接后面：当读者打开参考时，他们已经选择了要写什么。比率是每小时的写作和验证所解除的读者小时数，这不同于最频繁优先。

因素	问题	在比率中的作用
频率	有多少条记录，且在增长吗？	分子，高
解决成本	支持或读者花多长时间？	分子，高
影响范围	它阻止首次使用，还是打扰专家？	分子，中等
写作和验证工作量	一条命令可复现，还是花一周搭建环境？	分母
波动性	下个版本会改变答案吗？	分母——易变条目每个版本都要重新验证
可自助服务性	读者能否仅凭信息独自修复？	门控

对产生的四种聚类形状进行排序：

效率：频繁且可复现 > 首次使用阻塞 > 罕见且昂贵 > 易变
价值：首次使用阻塞 > 罕见且昂贵 > 频繁且可复现 > 易变
工作量：罕见且昂贵 > 易变 > 首次使用阻塞 > 频繁且可复现

默认先写频繁、可复现的聚类——它们每个只需一个下午，并且最快清空支持队列。一旦任何首次使用阻塞项位于注册到首次调用的路径上，就将其上移，因为在那里放弃的读者永远不会提交本可将该聚类排名的工单。

这种顺序会饿死罕见、昂贵的故障：每个读者花费数天，复现需要数天，记录太少无法排名，因此永远无法到达顶部。当它发生在生产环境中的合同约束客户身上，或出现在事件复盘中时，仍然提升它——这就是事件复盘信号来源存在的目的。

删除而非降级。未能通过自助服务门控的聚类完全离开队列：没有页面能帮助无法根据答案行动的读者。下一个版本移除的聚类也是如此——那是变更日志条目和产品工单，而不是被放在队列底部、悄然作为范围回来的页面。

排名是默认值，不是法律：它随谁在写作而移动。根据你已经知道的重新排名：

能在测试环境中复现的团队使罕见且昂贵的聚类便宜得多。
现有的支持宏使一个聚类几乎免费发布。
仅工单的信号混合会抬升付费客户所抱怨的故障的频率，同时隐藏静默故障。

向用户展示排序后的队列并在写作前获得同意：从错误聚类构建的队列会浪费整个写作过程。

Step 3 - Gate each cluster on document-versus-fix

步骤 3 - 对每个聚类进行文档与修复的门控

A troubleshooting page is a legitimate stopgap while a fix is scheduled. It is never the permanent answer for a failure the product could stop emitting. Documenting around a defect makes the defect permanent, and the page outlives everyone's memory of why it exists.

Not every diagnostic earns a page: Rust's compiler documents that "not all diagnostics have a code", reserving

--explain

entries for errors worth a durable explanation. Adopt the same gate rather than defaulting to "document everything".

Gate each cluster by where it sits against the escalation line:

Above the line - the same failure class recurs across several postmortems, or it dominates top-contact-driver analysis: escalate to product fix, say out loud that the page is an admission a defect is being tolerated, and name the owner.
Below the line: write the page.

The routing table is in ./references/signal-mining.md.

故障排除页面是修复计划期间的合法权宜之计。它永远不是产品本可以停止发出的故障的永久答案。围绕缺陷编写文档会使缺陷永久化，并且页面会比所有人对其存在原因的记忆更长寿。

并非每个诊断都值得一个页面：Rust 编译器记录了"并非所有诊断都有代码"，保留

--explain

条目给值得持久解释的错误。采用同样的门控，而不是默认"记录一切"。

根据聚类相对于升级线的位置进行门控：

线以上——同一故障类别在多个事后复盘中反复出现，或在 top-contact-driver 分析中占主导地位：升级为产品修复，公开说出页面是容忍缺陷的承认，并指定所有者。
线以下：编写页面。

路由表在 ./references/signal-mining.md 中。

Step 4 - Choose each entry's shape

步骤 4 - 选择每个条目的形状

Shape	Choose when	Reader arrives with
Error reference entry	The product emits a stable identifier	An exact string
Troubleshooting how-to	Symptoms without a code	A description of misbehaviour
Known-issues entry	Cause confirmed, fix unshipped	A suspicion it is not their fault

These three are deliberately unranked, unlike the cluster queue above. The evidence picks the shape (what the reader arrives holding), so an efficiency order over them would be false precision dressed as guidance - it would push writers to publish the cheap shape for a failure that needs the other one.

A coded error written as a prose how-to loses the string match.
A symptom forced into a code table loses the diagnosis.

When one symptom can come from several codes, write the how-to as a triage page that links to each entry.

形状	选择时机	读者到达时持有
错误参考条目	产品发出稳定的标识符	一个确切的字符串
故障排除操作指南	有症状但无代码	对错误行为的描述
已知问题条目	原因已确认，修复未发布	怀疑这不是他们的错

这三种有意不做排序，与上面的聚类队列不同。证据选择形状（读者到达时持有的东西），因此对它们进行效率排序将是伪装成指导的错误精确性——它会推动作者发布廉价的形状，而故障需要另一种。

将编码错误写成散文式操作指南会丢失字符串匹配。
将症状强行放入代码表会丢失诊断。

当一个症状可能来自多个代码时，将操作指南写成分诊页面，链接到每个条目。

Step 5 - Write the entry

步骤 5 - 编写条目

Every entry carries six parts, in this order. Parts 1-4 come from DITA's condition → cause → remedy plus KCS's environment field. Parts 5 and 6 are this skill's own additions, and they are the parts teams drop first:

Message: the error text verbatim, in a fenced block, only genuinely variable parts replaced by obvious placeholders.
Applies to: versions, platforms, plans, configurations. KCS calls this the environment field; without it the reader cannot tell whether the entry is about their case.
Cause: one or two sentences on what actually went wrong.
Fix: numbered executable steps, branched per cause, ordered by how often that check is the actual cause per minute of the reader's time. Not simply cheapest-first: a ten-second check that is never the cause still costs the reader a step. Several causes get several cause-remedy pairs, ordered as successive fall-backs.
Confirm it worked: the output or state that proves it. "It stopped erroring" also describes a second failure masking the first.
Still stuck: where to escalate and what to attach.

Follow three rules when drafting cause and fix:

Keep cause and fix separate: a reader who already knows the cause skips to the steps, and a reader who is guessing needs to confirm the cause before running commands.
Write in the reader's vocabulary - they know the symptom, not your subsystem names.
Never tell a reader the fix is "simple", "easy" or "just one step": it is not working for them right now, so the word reads as blame (Nielsen heuristic 9).

Write each cause-remedy pair so it stands alone. That is what a scanning human needs, and it is also what survives being chunked into a retrieval index - a block that depends on the paragraph above it retrieves as a fragment.

Templates for all three shapes, the microcopy style-guide comparison, a weak-versus-strong worked example, and the rules for quoting error text are in ./references/entry-templates.md.

每个条目包含六个部分，按此顺序。第 1-4 部分来自 DITA 的条件 → 原因 → 补救措施，加上 KCS 的环境字段。第 5 和第 6 部分是本 skill 自己的补充，也是团队最先丢弃的部分：

消息：逐字的错误文本，在围栏块中，仅将真正可变的替换为明显的占位符。
适用于：版本、平台、计划、配置。KCS 称之为环境字段；没有它，读者无法判断条目是否适用于他们的案例。
原因：一到两句话说明实际出了什么问题。
修复：编号的可执行步骤，按原因分支，按该检查实际上是原因的频率（每花费读者一分钟）排序。不单单是最便宜的优先：一个十秒的检查如果不是原因，仍然耗费读者一步。多个原因得到多个原因-修复对，按连续回退的顺序排列。
确认已修复：证明其有效的输出或状态。"它不再报错"也描述了第二个故障掩盖了第一个。
仍然卡住：升级到哪里以及附上什么。

起草原因和修复时遵循三条规则：

保持原因和修复分开：已经知道原因的读者跳到步骤，而猜测的读者需要先确认原因再运行命令。
使用读者的词汇——他们知道症状，不知道你的子系统名称。
永远不要告诉读者修复"简单"、"容易"或"只有一步"：它现在对他们无效，所以这个词读起来像责备（Nielsen 启发式 9）。

编写每个原因-修复对，使其独立。这是扫描中的人所需要的，也是被分块到检索索引中后能幸存下来的——依赖上文段落的块会作为片段被检索到。

所有三种形状的模板、微文案风格指南比较、弱与强的工作示例，以及引用错误文本的规则，都在 ./references/entry-templates.md 中。

Step 6 - Generate the catalog instead of hand-maintaining it

步骤 6 - 生成目录而非手动维护

Before writing a page per code, check whether the identifiers can come from one machine-readable source that both the product and the docs read. Hand-synced catalogs drift by default; generated ones cannot.

The published examples are unambiguous:

PostgreSQL's
```
src/backend/utils/errcodes.txt
```
generates both the C header and the SGML documentation table.
Rust's error index is auto-generated from
```
compiler/rustc_error_codes
```
, with RFC 1567 mandating description, erroneous example, explanation and fix per code.
Twilio publishes its error dictionary as downloadable JSON alongside the reference page.

Recommend this to the user as a one-off engineering task, not a docs task, and say what it buys: the code constant and the documented entry can never disagree again. See ./references/error-catalog-and-ai-surfaces.md.

在按代码编写页面之前，检查标识符是否来自一个产品和文档都读取的机器可读来源。手动同步的目录默认漂移；生成的目录不会。

公开示例是明确的：

PostgreSQL 的
```
src/backend/utils/errcodes.txt
```
同时生成 C 头文件和 SGML 文档表。
Rust 的错误索引从
```
compiler/rustc_error_codes
```
自动生成，RFC 1567 强制每个代码包含描述、错误示例、解释和修复。
Twilio 将其错误字典作为可下载的 JSON 与参考页面一起发布。

向用户推荐这作为一次性的工程任务，而不是文档任务，并说明其收益：代码常量和文档条目再也不会不一致。参见 ./references/error-catalog-and-ai-surfaces.md。

Step 7 - Verify before publishing

步骤 7 - 发布前验证

Verify each entry before publishing:

Reproduce the failure, run the fix exactly as written from the reader's starting state, and capture the post-fix signal.
Check the oldest supported version and the current one.
Have someone who did not write the entry follow it cold.

State the prerequisites each command assumes and what to do when that command itself fails. Steps written on a healthy machine routinely break on the reader's broken one.

An entry you could not reproduce ships only with an explicit "reported under these conditions, not reproduced here" note. Write the Docs puts the principle plainly: "Consider incorrect documentation to be worse than missing documentation." A confident, wrong fix costs more trust than an admitted gap.

The full protocol is in ./references/discoverability-and-metrics.md.

Strip credentials and customer identifiers from every example - a page that shows a whole token teaches readers to paste theirs into public issues.

在发布前验证每个条目：

复现故障，从读者的起始状态按编写的确切方式运行修复，并捕获修复后的信号。
检查最旧支持的版本和当前版本。
让未编写该条目的人冷启动地跟随它。

说明每个命令假设的前提条件，以及该命令本身失败时该怎么办。在健康机器上编写的步骤通常会在读者坏掉的机器上失效。

无法复现的条目仅在带有明确的"在所述条件下报告，此处未复现"说明时发布。Write the Docs 明确表述了这一原则："认为不正确的文档比缺失的文档更糟。"一个自信的错误修复比一个承认的差距更消耗信任。

完整协议在 ./references/discoverability-and-metrics.md 中。

从每个示例中去除凭据和客户标识符——一个显示完整 token 的页面会教读者将其粘贴到公共 issue 中。

Step 8 - Make the page findable

步骤 8 - 使页面可被发现

Readers paste the error string; nobody browses a troubleshooting section speculatively. So:

Put the string verbatim in the title, the first heading and the body.
Give each error one addressable target: its own page, or a stable anchor on a codes page.
Answer in the first screen: message, cause, first fix, before any feature preamble.
Repeat the error string on every entry that shares it instead of linking readers to a common section. Write the Docs' ARID principle - "Accept (some) Repetition In Documentation" - exists for exactly this case: the match matters more than the duplication.
Link the entry from where the failure happens, and from the product itself where you can: a documentation URL in the error payload, an
```
explain <code>
```
path in the CLI.
Keep identifiers and URLs stable; renaming a code invalidates every link and cached answer pointing at it.

Skip FAQ structured data - Google's FAQ rich result no longer appears in search, so marking troubleshooting content as

FAQPage

buys nothing. ./references/discoverability-and-metrics.md has the historical detail and what else no longer works.

When an assistant answers from these docs (interview question above), publishing ends at re-index, not at merge - otherwise a corrected page keeps being answered from the stale index. Trigger a re-embed when:

the embedding model improves,
roughly 10-15% of the content has changed (practitioner guidance from a docs-assistant vendor, not a measured threshold), or
the domain shifts.

See ./references/error-catalog-and-ai-surfaces.md.

读者粘贴错误字符串；没有人会投机地浏览故障排除部分。因此：

将字符串逐字放在标题、第一个标题和正文中。
给每个错误一个可寻址的目标：其自己的页面，或代码页面上的稳定锚点。
在第一屏中回答：消息、原因、第一个修复，在任何功能前言之前。
在每个共享该字符串的条目上重复错误字符串，而不是链接到公共部分。Write the Docs 的 ARID 原则——"Accept (some) Repetition In Documentation"——正是为此而存在：匹配比重复更重要。
从故障发生的位置链接条目，并尽量从产品本身链接：错误负载中的文档 URL，CLI 中的
```
explain <code>
```
路径。
保持标识符和 URL 稳定；重命名一个代码会使指向它的每个链接和缓存答案失效。

跳过 FAQ 结构化数据——Google 的 FAQ 富结果不再出现在搜索中，因此将故障排除内容标记为

FAQPage

毫无收益。./references/discoverability-and-metrics.md 有历史细节和其他不再有效的内容。

当助手从这些文档回答时（上面的访谈问题），发布以重新索引结束，而不是合并——否则，纠正后的页面仍会从过时的索引中被回答。在以下情况触发重新嵌入：

嵌入模型改进，
大约 10-15% 的内容已更改（来自文档助手供应商的实践指导，而非测量阈值），或
领域转变。

参见 ./references/error-catalog-and-ai-surfaces.md。

Step 9 - Set the target and measure

步骤 9 - 设定目标并衡量

Set expectations against the published ceiling before promising anything. Gartner's December 2023 survey of 5,728 customers found only 14% of customer service issues fully resolved in self-service, and only 36% even for issues customers rated "very simple". "Reduce this to zero tickets" is not a defensible objective; "raise the share resolved without a ticket" is.

Set the coverage target with the user before writing. 80% of the top 20 clusters within the cycle is this skill's self-set baseline, not a published benchmark - negotiate it against the team's real capacity and say which number you agreed on.

Track:

cluster coverage
ticket volume per covered error on fixed windows
zero-result docs searches for covered strings
the share of entries touched since the last release

Prefer resolution rate and cost per resolution over raw deflection rate - a deflection number looks good while readers repeatedly fail and re-contact. Per-error deflection is measurable; a site-wide "deflection rate" is not.

Refuse to quote the folklore statistics that circulate in this field. The commonly repeated "a support ticket costs $15-$50" figure and most published deflection percentages have no traceable methodology. Use the customer's own ticket costs, or say the number is unknown.

When a sceptical stakeholder needs a sourced argument for the work, use the Dixon/Freeman/Toman loyalty research quoted in ./references/discoverability-and-metrics.md.

在承诺任何事情之前，对照已发布的基准设定期望。Gartner 2023 年 12 月对 5,728 名客户的调查发现，只有 14% 的客户服务问题在自助服务中完全解决，即使对于客户评为"非常简单"的问题也只有 36%。"将工单降至零"不是站得住脚的目标；"提高无需工单即可解决的比例"才是。

在写作之前与用户设定覆盖目标。周期内前 20 个聚类的 80% 是本 skill 的自设基线，不是已发布的基准——根据团队的实际能力进行协商，并说明你同意的数字。

跟踪：

聚类覆盖率
固定窗口内每个已覆盖错误的工单量
覆盖字符串的零结果文档搜索
自上次发布以来被触及的条目比例

优先选择解决率和每次解决的成本，而非原始转移率——当读者反复失败并再次联系时，转移数字看起来不错。每个错误的转移是可测量的；全站"转移率"不可测量。

拒绝引用此领域中流传的民间统计。常被重复的"支持工单花费 15-50 美元"的数字和大多数已发布的转移百分比没有可追溯的方法论。使用客户自己的工单成本，或者说数字未知。

当持怀疑态度的利益相关者需要基于来源的论证时，使用 ./references/discoverability-and-metrics.md 中引用的 Dixon/Freeman/Toman 忠诚度研究。

Step 10 - Maintain

步骤 10 - 维护

Re-run the clustering pass after publication and compare. The same clusters reappearing unchanged means the entries are not being found - a discoverability problem, not a volume problem.

Book the maintenance triggers now:

A release that changes an error's text or cause updates the entry in the same release.
A shipped fix retires the known-issues entry.
A dead escape-hatch channel gets fixed everywhere it appears.

Stamp each page with a last-verified date and an owner so staleness is visible without reading the page.

If your environment has persistent memory, store the durable decisions:

the signal sources and their export paths
the agreed cluster ranking
the negotiated coverage target
the clusters deliberately routed away from docs, and why

The next pass is a diff against those; re-deriving them each cycle is where this work usually dies.

发布后重新运行聚类并通过比较。同样的聚类原样重现意味着条目没有被找到——这是可发现性问题，不是数量问题。

现在就预订维护触发器：

改变错误文本或原因的版本发布会在同一发布中更新条目。
已发布的修复使已知问题条目退役。
一个死掉的逃生舱通道在其出现的每个地方被修复。

给每个页面盖上最后验证日期和所有者，这样过时性无需阅读页面即可可见。

如果你的环境有持久记忆，存储持久决策：

信号来源及其导出路径
商定的聚类排序
协商的覆盖目标
被有意路由离开文档的聚类及其原因

下一次通过的差异将针对这些；每个周期重新推导它们通常会导致这项工作消亡。

Invocation examples and expected output

调用示例和预期输出

Typical invocations:

"turn our support tickets into troubleshooting docs"
"we need a page for every error code"
"the same three errors flood Discord every week"
"our error docs exist but nobody finds them"
"write a known-issues page for the 2.0 release"

A full pass returns four artefacts, in this order:

Ranked cluster queue: a table of clusters (
```
count
```
,
```
first_seen
```
,
```
last_seen
```
, one raw sample, proposed shape, page/product/macro routing), with the agreed coverage target stated as a number.
Entry drafts: one file per entry, six parts each, in the docs site's own format.
Verification log: per entry, version reproduced on, the fix executed, the observed post-fix signal, or an explicit "not reproduced" note.
Wiring and measurement plan: where each entry is linked from, which product surface carries the link, the metrics baseline, and the maintenance triggers with owners.

Stop and report at the queue if the user has not agreed the ranking, and at the verification log if a fix could not be executed.

典型调用：

"将我们的支持工单转化为故障排除文档"
"我们需要每个错误码一个页面"
"每周三个相同的错误淹没 Discord"
"我们的错误文档存在但没人找到它们"
"为 2.0 版本编写已知问题页面"

一次完整的过程返回四个工件，按此顺序：

排序后的聚类队列：聚类表（
```
count
```
、
```
first_seen
```
、
```
last_seen
```
、一个原始样本、建议的形状、页面/产品/宏路由），并将商定的覆盖目标以数字形式说明。
条目草稿：每个条目一个文件，每文件六个部分，使用文档站自身的格式。
验证日志：每个条目，在其上复现的版本、执行的修复、观察到的修复后信号，或明确的"未复现"说明。
接线和测量计划：每个条目的链接位置，哪个产品表面携带链接，度量基线，以及带有所有者的维护触发器。

如果用户尚未同意排序，则在队列处停止并报告；如果修复无法执行，则在验证日志处停止并报告。

Failure modes

故障模式

Failure	What it looks like	Fix
Imagined failures	Entries for errors nobody hit	Write only from clustered evidence
One page per ticket	Six pages, one cause	Cluster first, then write
Most-frequent-first queue	The rare failure that costs days per reader is never written	Rank by reader-hours unblocked per writing hour; promote incident-review clusters by hand
Missing error string	"Authentication problems" as the title	Verbatim string in title, heading and body
Prettified message	Cleaned-up, re-wrapped error text	Copy from a real run, placeholder only the variable parts
Cause without fix	Explains the subsystem, no steps	Numbered steps, branched per cause
Fix without confirmation	Reader cannot tell it worked	State the expected post-fix signal
Unverified fix	Steps written from memory	Reproduce and execute before publishing
Healthy-machine steps	Commands that assume a working setup	State prerequisites and the per-step failure branch
Documenting a defect	A page that exists because the message is bad	Route to the product; note it in the queue
Hand-synced catalog	Docs table and code enum disagree	Generate both from one source file
Folklore statistics	"$25 per deflected ticket" in the business case	Use the team's own numbers or say it is unknown
Stale retrieval index	Corrected page, wrong AI answer	Re-index on the content-change trigger
Dead escape hatch	"Contact support" pointing at a closed channel	Name a watched channel and the attachments to include
Zombie known issues	Entries for bugs fixed three releases ago	Retire on release, with a version note

失败	看起来像	修复
想象故障	没有人遇到的错误的条目	仅从聚类证据编写
每个工单一页	六个页面，一个原因	先聚类，再编写
最频繁优先队列	每个读者花费数天的罕见故障从未编写	按每次写作小时解除的读者小时数排名；手动提升事件复盘聚类
缺少错误字符串	"身份验证问题" 作为标题	标题、标题和正文中的逐字字符串
美化消息	清理过、重新换行的错误文本	从真实运行复制，仅占位符替换可变部分
有原因无修复	解释子系统，无步骤	编号步骤，按原因分支
有修复无确认	读者无法判断是否有效	说明预期的修复后信号
未验证的修复	凭记忆编写的步骤	发布前复现并执行
健康机器步骤	假设工作设置的命令	说明前提条件和每步失败分支
记录缺陷	因为消息不好而存在的页面	路由到产品；在队列中注明
手动同步目录	文档表和代码枚举不一致	从一个源文件生成两者
民间统计	业务案例中的"每次转移工单 25 美元"	使用团队自己的数字或说未知
过时的检索索引	已纠正的页面，错误的 AI 回答	在内容更改触发器时重新索引
死掉的逃生舱	"联系支持" 指向关闭的渠道	指定一个受关注的渠道和要包含的附件
僵尸已知问题	三个版本前已修复的 bug 的条目	在发布时退役，附版本说明

References

参考

./references/signal-mining.md - Signal sources, audience differences, the KCS capture loop and role ladder, helpdesk promote-to-article features, the queue cut-off and the document-versus-fix routing table
./references/entry-templates.md - The three page templates, the error-message style-guide comparison, a weak-versus-strong worked example and the error-text quoting rules
./references/error-catalog-and-ai-surfaces.md - Generating a catalog from one source of truth and serving these pages to retrieval-based assistants
./references/discoverability-and-metrics.md - Findability wiring, the verification protocol, sourced benchmarks, metrics and maintenance triggers
samber/developer-relations-skills@coding-agent-docs-optimization - Designing machine-facing entry points across a whole SDK or API surface
samber/developer-relations-skills@devrel-metrics - The wider measurement framework
samber/developer-relations-skills@oss-issue-triage - Routes a repeat-question issue into a new troubleshooting entry instead of leaving it open

./references/signal-mining.md - 信号来源、受众差异、KCS 捕获循环和角色阶梯、帮助台提升为文章功能、队列截止和文档与修复路由表
./references/entry-templates.md - 三种页面模板、错误消息风格指南比较、弱与强工作示例和错误文本引用规则
./references/error-catalog-and-ai-surfaces.md - 从单一可信来源生成目录并服务于基于检索的助手
./references/discoverability-and-metrics.md - 可发现性接线、验证协议、基于来源的基准、度量指标和维护触发器
samber/developer-relations-skills@coding-agent-docs-optimization - 设计整个 SDK 或 API 表面的面向机器入口点
samber/developer-relations-skills@devrel-metrics - 更广泛的测量框架
samber/developer-relations-skills@oss-issue-triage - 将重复问答 issue 路由到新的故障排除条目，而不是保持开放