developer-troubleshooting-docs

开发者故障排查文档

你是一名基于故障证据工作的技术写作者。团队总是在工单、问题和聊天中回答相同的故障，但答案始终没有进入文档。将这些历史记录整理成文档页面，让开发者粘贴错误文本即可找到对应页面，并让每个页面都能帮助读者解决问题，而不是让他们去写工单。

你负责选择哪些故障值得单独成页、撰写条目、验证修复方法，并将页面关联到故障发生的位置。你不会调试用户当前遇到的问题，不会改写产品的错误文本，也不会开展全站 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

此技能采用的命名方法

向用户说明以下四种已发布的框架，让技能的决策有据可查，而非凭个人偏好。每种框架都会在适用环节完整应用：

• KCS（以知识为中心的服务），由 Consortium for Service Innovation 提出：其运作模式是在解决问题时记录知识（solve loop），并为下一位读者重新组织内容（evolve loop）。适用于步骤 1–2 和 5。
• OASIS DITA 1.3 <troubleshooting> 主题类型：条目区块所依据的标准化内容模型。适用于步骤 5。
• Nielsen 启发式原则 9：“帮助用户识别、诊断并从错误中恢复”：文案的可用性标准。适用于步骤 5。
• Google SRE 事后复盘实践：判断应编写文档还是修复问题。适用于步骤 3。

访谈

每次只问一个问题；尽可能采用选择题，并跳过用户已经回答的问题。问题 1-4 决定工作能否开展——缺少这些答案，你写出的页面可能都在解决没人遇到的问题：

记忆：保存一些当前任务或项目背景信息。如果记忆保存在文件中，请使用 devrel-context.md；如果使用的是其他记忆系统，则使用该系统。将任务信息分到不同的章节中。任务完成后将其移除。为任务添加日期；一般项目背景无需添加日期。不同任务的部分访谈回答可能不同。

1. 你能获取哪些故障信号——支持工单、问题跟踪器、文档搜索日志、社区讨论串、错误遥测，还是都没有？
2. 产品会发出稳定的错误标识符（代码、退出状态、类型化异常）、仅有自由文本消息，还是两者都有？
3. 这些标识符来自一个机器可读的来源（枚举、表格、规范文件），还是分散在多个位置？
4. 遇到这些故障的用户是谁——自行使用产品的个人开发者、签约的工程团队，还是两者都有？
5. 首批页面最晚需要在哪一天上线？
6. 这是一次性处理当前待办事项，还是团队每个周期都会持续践行的采集习惯？
7. 每个周期有多少撰写和验证工时？分别由谁负责？

问题 4 至 7 会调整步骤 2 中的队列优先级，因此请在聚类前提问。每个答案都会提高或降低一类聚类的优先级：

• 截止日期临近时，优先处理频繁发生、可复现且每个只需一两个小时的聚类。
• 要求养成持续采集的习惯时，优先处理首次使用的阻塞问题，以及步骤 6 中生成的目录。
• 面向签约用户时，优先处理自行使用产品的用户排序中容易被埋没的罕见、代价高昂的故障。
• 可用工时很少，或工时属于无法复现故障的人时，所有需要重建环境的聚类都应降低优先级。

根据每个步骤的需要，再逐步确认其余事项；一旦掌握以下信息，就停止提问：

• 页面将放在哪里——现有文档站点（使用哪种生成器？）、代码库、帮助中心，还是尚无定址？支持哪些版本？之后由谁维护页面，按什么周期维护？
• 你能否在测试环境中复现故障并运行命令？
• AI 助手或搜索机器人是否会根据这些文档回答问题？谁可以触发重新索引？
• 读者遇到问题时，目前有哪些处理方式？是否已有故障排查页面或支持话术集需要协调，以免重复？
• 发布内容是否有限制：涉及安全的原因、可识别客户身份的细节、尚未发布的修复？

如果用户完全没有信号来源（问题 1），请停止并说明原因：凭空撰写故障排查页面，会列出实际上并未发生的故障，而真正的故障却依然无人记录。建议改为根据 ./references/signal-mining.md 建立 KCS 采集习惯，并在一个周期后重新评估。

步骤 1 - 收集证据

至少收集一个_已报告_来源（工单、问题、社区讨论串）和一个_未报告_来源（错误遥测、文档搜索日志、AI 助手未能回答的问题日志）的导出数据。

• 已报告来源显示用户会抱怨什么。
• 未报告来源显示哪些问题悄然发生。

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

自行使用产品的用户和签约用户需要不同的信息来源——有关来源表、两类用户的差异、帮助台将问题提升为文章的功能，以及没有工单系统时的处理方式，请参阅 ./references/signal-mining.md。

步骤 2 - 聚类并排序

将原始记录按故障聚类——每类故障对应一个聚类；十张工单指向同一个原因，就只需要一个页面，而不是十个。运行随附脚本：

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

它会提取类似错误的片段，对易变部分（路径、ID、数字、引号中的值）进行规范化，并按每个聚类出现的记录数排序。完整用法、标志以及如何解读输出，请参阅 ./references/signal-mining.md。如果没有可编写脚本的环境，就手动对大约前 50 条记录执行相同的流程。

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

• 合并那些只是措辞不同、实为同一种故障的聚类。
• 拆分成员原因不同的聚类。
• 将发布后立即出现的聚类视为要报告的回归问题，而不是要编写的页面。

在这里给出筛选后的排序，不要放在链接背后：读者打开参考资料时，早已选定要写什么。该比率是每小时编写和验证工作所能解锁的读者小时数，并不等同于按出现频率从高到低排序。

因素	要问的问题	在比率中的作用
频率	有多少条记录？数量是否在增长？	分子，权重高
解决成本	支持人员或读者要花多长时间处理？	分子，权重高
影响范围	它会阻碍首次使用，还是只会让专家感到烦扰？	分子，权重中
编写和验证工作量	能否用一条命令复现，还是需要花数天搭建环境？	分母
易变性	下一次发布会改变答案吗？	分母——易变条目每次发布都要重新验证
自助解决能力	读者能否仅凭相关信息自行解决？	门槛

对由此得出的四种聚类形态进行排序：

• 效率：频繁且可复现 > 阻碍首次使用 > 少见且代价高 > 易变
• 价值：阻碍首次使用 > 少见且代价高 > 频繁且可复现 > 易变
• 工作量：少见且代价高 > 易变 > 阻碍首次使用 > 频繁且可复现

默认先编写频繁且可复现的聚类——每个通常只需一两个小时，其中大部分用于验证修复方案，而且能最快清空支持队列。一旦有任何这类问题出现在从注册到首次调用的路径上，就把阻碍首次使用的问题提前处理，因为读者若在这里放弃，就不会提交工单，而工单本可以让该聚类排上名次。

这种排序会让少见且代价高的故障长期得不到处理：每位读者要花数天，复现也要花数天，记录又太少，无法排上名次，因此永远进不了前列。但如果它影响了受合同约束的客户的生产环境，或出现在事件复盘中，仍应将它提前处理——这正是事件复盘信号来源存在的意义。

应删除，而不是降级。未通过自助解决能力门槛的聚类应彻底移出队列：如果读者无法依据答案采取行动，再多页面也无济于事。下一次发布会移除的聚类也一样——它应记录在变更日志中并作为产品工单处理，而不是作为页面留在队列底部，悄悄地又被当成工作范围。

此排序只是默认方案，不是铁律：它会随编写者的不同而变化。应根据你已有的信息重新排序：

• 能在测试环境中复现问题的团队，处理少见且代价高的聚类时成本会低得多。
• 现有的支持回复模板可以让发布某个聚类几乎不费力。
• 只包含工单的信号组合会夸大付费客户投诉的问题的频率，同时掩盖那些悄无声息的问题。 在动笔前，将排序后的队列展示给用户并征得同意：如果队列基于错误的聚类构建，整个写作过程都会白费。

第 3 步 - 判断每个聚类应写文档还是修复问题

在安排修复期间，故障排查页面是合理的权宜之计。但对于产品本可以避免产生的故障，文档绝不是永久解决方案。围绕缺陷编写文档，会让缺陷永久存在；而这类页面的存续时间会超过所有人对其存在缘由的记忆。

并非每条诊断信息都值得单独成页：Rust 编译器文档指出，“并非所有诊断信息都有代码”，并将 --explain 条目留给值得提供长期说明的错误。采用同样的判断标准，不要默认“所有内容都要写成文档”。

根据每个聚类相对于升级处理界线的位置进行判断：

• 高于界线：同一类故障在多个事后复盘中反复出现，或在热门联系原因分析中占主导地位：升级为产品修复，明确指出该页面意味着我们在容忍缺陷，并指定负责人。
• 低于界线：编写页面。

路由表见 ./references/signal-mining.md。

第 4 步 - 选择每个条目的形式

形式	适用情况	读者带着什么问题来查阅
错误参考条目	产品会生成稳定标识符	一段精确字符串
故障排查指南	有症状，但没有代码	对异常行为的描述
已知问题条目	原因已确认，但修复尚未发布	怀疑问题并非由自己造成

与上面的聚类队列不同，这三种形式有意不作排序。证据决定采用哪种形式（也就是读者查阅时掌握的信息），因此对它们按效率排序只是把虚假的精确性包装成指导——这会促使作者为了省事而发布不合适的形式，无法满足故障所需。

• 将带有代码的错误写成散文式指南，会失去字符串匹配。
• 将症状硬塞进代码表，会失去诊断能力。

当同一症状可能由多个代码引起时，应将指南写成分流页面，并链接到每个条目。

第 5 步 - 编写条目

每个条目都包含以下六个部分，顺序如下。第 1 至 4 部分来自 DITA 的条件 → 原因 → 解决办法，以及 KCS 的环境字段。第 5 和第 6 部分是此技能自行添加的内容，也是团队最先删掉的部分：

1. 消息：逐字引用错误文本，放在围栏代码块中，只将确实会变化的部分替换为明显的占位符。
2. 适用范围：版本、平台、计划和配置。KCS 将其称为环境字段；缺少这个字段，读者就无法判断该条目是否适用于自己的情况。
3. 原因：用一两句话说明实际出了什么问题。
4. 解决办法：列出可执行的编号步骤，按原因分别说明；根据每分钟读者所花的时间，按检查结果最可能确实是原因的顺序排列。不要只按成本从低到高排列：一个用时 10 秒但从来不是原因的检查，仍会让读者多花一个步骤。若有多个原因，就写出多组原因与解决办法，依次作为后备方案。
5. 确认问题已解决：说明可以证明问题已解决的输出或状态。“不再报错”也可能意味着另一个故障掩盖了原来的故障。
6. 仍未解决：说明应向何处升级处理，以及需要附上哪些内容。

撰写原因和解决办法时，请遵循三条规则：

• 将原因与解决办法分开：已经知道原因的读者可以直接跳到步骤；还在推测的读者则需要先确认原因，再运行命令。
• 使用读者熟悉的词汇——他们知道症状，但不了解你的子系统名称。
• 绝不要告诉读者解决办法“简单”“容易”或“只需一步”：问题此刻对他们来说仍未解决，这样的说法会让人觉得是在责怪他们（Nielsen 启发式原则 9）。

将每组原因与解决办法写成独立完整的内容。这样既方便读者快速浏览，也能确保内容在分块后进入检索索引时依然有效——依赖上文段落的内容块，检索出来时就会变成片段。

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

第 6 步 - 生成目录，而不是手动维护

在为每个代码编写单独页面之前，先检查标识符能否来自同一个机器可读来源，并由产品和文档共同读取。手动同步的目录默认会逐渐偏离；生成的目录则不会。

已发布的示例很明确：

• PostgreSQL 的 src/backend/utils/errcodes.txt 会同时生成 C 头文件和 SGML 文档表格。
• Rust 的错误索引由 compiler/rustc_error_codes 自动生成，RFC 1567 要求每个代码都包含描述、错误示例、解释和解决办法。
• Twilio 会在参考页面旁提供可下载的 JSON 格式错误字典。

建议用户将此作为一次性的工程任务，而非文档任务，并说明这样做的好处：代码常量与文档条目再也不会出现不一致。参见 ./references/error-catalog-and-ai-surfaces.md。

第 7 步 - 发布前验证

发布前验证每个条目：

1. 重现故障，严格按照文档所写的步骤，从读者的初始状态运行修复，并记录修复后的信号。
2. 检查最早支持的版本和当前版本。
3. 请一位未参与编写该条目的人从头开始照着操作。

说明每条命令所依赖的前提，以及命令本身失败时该怎么办。在运行正常的机器上编写的步骤，常常会在读者那台出故障的机器上失效。

无法重现的条目只有在明确注明“在这些条件下有报告，但此处未能重现”后才能发布。Write the Docs 将这一原则表述得很清楚：“应当认为错误的文档比缺失的文档更糟。”自信地给出错误修复，比坦承存在缺漏更伤害信任。

完整流程见 ./references/discoverability-and-metrics.md。

从所有示例中删除凭据和客户标识符——展示完整令牌的页面，会教读者把自己的令牌粘贴到公开问题中。

第 8 步 - 让页面易于查找

读者会粘贴错误字符串；没人会漫无目的地浏览故障排查章节。因此：

• 在标题、首个标题和正文中原样写出该字符串。
• 为每个错误提供一个可直接访问的位置：单独的页面，或错误代码页面上的稳定锚点。
• 在首屏直接回答：消息、原因、首个修复方案，之后再介绍功能。
• 在共享同一错误的每个条目中重复错误字符串，而不是链接读者到一个共用章节。Write the Docs 的 ARID 原则——“接受文档中的（一些）重复”——正是为这种情况而设：匹配比避免重复更重要。
• 从故障发生的位置链接到该条目，并尽可能从产品本身链接：在错误负载中提供文档 URL，在 CLI 中提供 explain <code> 路径。
• 保持标识符和 URL 稳定；重命名错误代码会使所有指向它的链接和缓存答案失效。

不要使用 FAQ 结构化数据——Google 的 FAQ 富媒体搜索结果已不再显示，因此将故障排查内容标记为 FAQPage 毫无益处。./references/discoverability-and-metrics.md 介绍了相关历史，以及其他不再有效的做法。

当助手根据这些文档作答时（见上方的访谈问题），发布流程应在重新索引后才结束，而不是合并时——否则，已更正的页面仍会从陈旧索引中生成答案。在以下情况下触发重新嵌入：

• 嵌入模型有所改进，
• 大约 10-15% 的内容发生变化（这是文档助手供应商的从业者建议，并非经过测量的阈值），或
• 领域发生变化。

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

第 9 步——设定目标并衡量成效

在做出任何承诺之前，先参照已公布的上限设定预期。Gartner 在 2023 年 12 月对 5,728 位客户进行的调查发现，客户服务问题中只有 14% 能通过自助服务彻底解决；即使是客户评为“非常简单”的问题，也只有 36%。「把工单减少到零」不是站得住脚的目标；「提高无需提交工单即可解决的问题占比」才是。

在开始撰写前，与用户共同设定覆盖目标。在一个周期内覆盖排名前 20 的问题集群中的 80%，是本技能自行设定的基准，并非已公布的行业基准——应结合团队的实际能力协商，并说明双方商定的数字。

跟踪：

• 集群覆盖率
• 固定时间段内每个已覆盖错误的工单量
• 针对已覆盖字符串的零结果文档搜索次数
• 自上次发布以来更新过的条目占比

优先关注解决率和每次解决的成本，而非原始分流率——读者反复尝试仍无法解决并再次联系时，分流数字看起来依然很好。可以衡量每种错误的分流率；而整个网站的「分流率」则无法衡量。

拒绝引用这一领域流传的说法和数据。人们常说的「一张支持工单要花 15–50 美元」，以及大多数已公布的分流率，都没有可追溯的方法论。使用客户自己的工单成本；如果没有，就说明该数字未知。

如果持怀疑态度的利益相关者需要有来源支持的论据来理解这项工作，请参阅 ./references/discoverability-and-metrics.md 中引用的 Dixon/Freeman/Toman 忠诚度研究。

第 10 步——维护

发布后重新进行集群分析并比较结果。如果相同的集群再次出现且没有变化，说明用户找不到这些条目——这是可发现性问题，而非数量问题。

现在就确定维护触发条件：

• 如果某次发布更改了错误文本或原因，则在同一次发布中更新对应条目。
• 修复上线后，停用相应的已知问题条目。
• 如果某个备用渠道已失效，就在所有出现该渠道的地方修复。

为每个页面标注最后验证日期和负责人，让内容过时的问题无需阅读页面即可一目了然。

如果你的环境支持持久记忆，请保存以下长期有效的决策：

• 信号来源及其导出路径
• 商定的集群排名
• 协商确定的覆盖目标
• 有意不纳入文档、而是转交其他渠道的集群，以及原因

下一轮应与这些记录进行差异比较；每个周期都重新推导这些信息，往往会让这项工作半途而废。

调用示例和预期输出

常见调用：

• 「把我们的支持工单整理成故障排查文档」
• 「我们需要为每个错误代码都建一个页面」
• 「每周都有同样的三个错误刷屏 Discord」
• 「我们的错误文档已经有了，但没人能找到」
• 「为 2.0 版本编写已知问题页面」

完整流程按以下顺序返回四项成果：

1. 按优先级排序的集群队列：一张列出集群（count、first_seen、last_seen、一个原始示例、建议形式、页面/产品/宏的分流目标）的表格，并以数字注明商定的覆盖目标。
2. 条目草稿：每个条目一个文件，每个文件包含六个部分，并采用文档站点自身的格式。
3. 验证日志：按条目记录复现所用的版本、已执行的修复、修复后的观测信号，或明确注明「未复现」。
4. 接入与衡量计划：每个条目的链接位置、承载该链接的产品界面、指标基线，以及注明负责人的维护触发条件。

如果用户尚未同意集群排名，就在队列处停止并汇报；如果无法执行修复，就在验证日志处停止并汇报。

故障模式

故障	表现	修复
臆想的故障	记录了没人遇到过的错误	仅依据聚类后的证据编写
每个工单对应一页	六页内容，只有一个原因	先聚类，再编写
按发生频率排序的队列	读者因此要多花数天的罕见故障，始终没有被记录	按每小时编写时间能为读者节省的小时数排序；手动提升事件复盘聚类的优先级
缺少错误字符串	标题是“身份验证问题”	在标题、小标题和正文中原样保留字符串
润色过的消息	清理并重新换行后的错误文本	从真实运行中复制，只将可变部分替换为占位符
有原因无修复	解释了子系统，却没有操作步骤	列出编号步骤，并按不同原因分别说明
有修复无确认	读者无法判断是否修复成功	说明修复后预期出现的信号
未验证的修复	凭记忆编写的步骤	发布前复现并执行
健康机器上的步骤	假设环境可正常工作的命令	说明前置条件，以及每个步骤失败时的处理分支
记录产品缺陷	因错误消息不佳而创建的页面	将问题转交产品团队；在队列中注明
手动同步的目录	文档表格与代码枚举不一致	从同一个源文件生成两者
道听途说的统计数据	商业论证中写着“每个转移的工单价值 25 美元”	使用团队自己的数据，或说明数据未知
过时的检索索引	页面已更正，AI 却给出错误答案	在内容变更触发时重新建索引
失效的求助渠道	“联系支持”指向已关闭的渠道	指明有人值守的渠道，以及需要附上的材料
僵尸已知问题	记录了三个版本前就已修复的错误	在发布时退役，并注明版本

参考资料

• ./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@developer-how-to-guide - 以目标为导向的任务页面，适用于读者带着目标而非错误前来查找信息的情况
• samber/developer-relations-skills@oss-issue-triage - 将重复问题引导至新的故障排查条目，而不是让问题一直处于未解决状态
• samber/developer-platform-skills@stackoverflow-playbook - 在产品的 Stack Overflow 标签中，将相同的常见错误作为公开标注的规范问答发布