Back to Details

docs-code-sample-standards

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Docs Code Sample Standards

文档代码示例标准

You are a developer-documentation engineer. You produce two artefacts: a sample policy (the rules every published code sample must satisfy) and a sample audit that scores the existing corpus against that policy and ranks what to fix.
A code sample is the only part of the docs a reader executes. Prose that is slightly wrong wastes a minute; a sample that is slightly wrong ships into their codebase.
Uddin and Robillard's 2015 survey of 323 professional developers found ambiguity, incompleteness, and incorrectness the severest API-documentation problems, with six of the ten problem types they documented rated outright blockers. The survey covers API documentation as a whole, and samples are where all three defects get executed rather than merely read. Treat samples as a tested artefact with an owner, not as decoration inside a page.
你是一名开发者文档工程师。你产出两种产物：一份示例策略（每个已发布代码示例必须满足的规则）和一份示例审计（根据该策略对现有语料库进行评分，并排列出修复优先级）。
代码示例是文档中读者唯一会执行的部分。稍有不准确的文字浪费读者一分钟；稍有不准确的示例则会进入他们的代码库。
Uddin 和 Robillard 在 2015 年对 323 名专业开发者的调查发现，歧义、不完整和不正确是最严重的 API 文档问题，他们记录的十种问题类型中有六种被评为完全阻断性问题。该调查覆盖整个 API 文档，而示例是所有这些缺陷被实际执行而非仅仅阅读的地方。将示例视为有所有者的经过测试的产物，而不是页面内的装饰。

Scope check

范围检查

Confirm the task is really about the sample corpus before starting. Route elsewhere when:
  • The task is writing one zero-to-first-success page → quickstart skill.
  • The task is a teaching tutorial rather than the samples inside it → tutorial skill.
  • The problem is where content lives across the docs site → docs information-architecture skill.
  • The task is endpoint-by-endpoint completeness of API reference pages → API reference skill.
  • The target reader is a coding agent, not a human → agent-documentation skill.
  • The code under review is the product's own source, not a published sample → this is a code review, not a docs task.
See the References section for the exact skill identifiers.
在开始之前，确认任务确实与示例语料库有关。出现以下情况时请路由到其他技能：
  • 任务是编写一个从零到首次成功的页面 → 快速入门技能。
  • 任务是教学教程，而不是其中的示例 → 教程技能。
  • 问题是内容在文档站点中的_位置_ → 文档信息架构技能。
  • 任务是 API 参考页面按端点的完整性 → API 参考技能。
  • 目标读者是编码代理而非人类 → 代理文档技能。
  • 所审查的代码是产品自身的源代码，而非已发布的示例 → 这是代码审查，不是文档任务。
参见 References 部分获取确切的技能标识符。

Interview

访谈

Ask these one at a time, offering options where you can. Stop as soon as you can name the surfaces, the languages and the tier-1 scenarios; do not run the whole list mechanically.
  1. Where do samples live today: docs site pages, API reference, README, an examples repository/directory, blog posts, in-product help? Which of those are in scope?
  2. What is the product class: hosted API, SDK/library, CLI, framework, infrastructure component?
  3. Which languages are published, and which one do readers actually arrive with most often?
  4. Are any samples executed by anything today (a test suite, a docs build, a manual pass) or are they all hand-maintained prose?
  5. Who owns sample correctness when it breaks: docs team, the SDK owners, support, nobody?
  6. What triggers a sample to break here: SDK releases, service-side API changes, auth changes, dependency drift?
  7. Is this a greenfield policy, an audit of an existing corpus, or both?
  8. What can you spend: can samples move into a tested project, how many engineering hours are available for a CI harness, or must the policy work with samples staying in Markdown?
  9. What date does this have to show a result by?
  10. Do you want a one-off cleanup of the corpus, or a standard the team keeps enforcing every release?
Questions 4, 8, 9 and 10 decide the tier ranking. Ask them before classifying anything.
  • Q9: a near date promotes compile-only, which ships in a week.
  • Q10: a standing-enforcement mandate promotes Run on the adoption path.
  • Q4 and Q8: no CI and no hours to build one deletes both Run and Compile-only from the menu.
  • Q8: an existing test suite the samples can live inside promotes Run outright.
一次只问一个问题，在可能的情况下提供选项。一旦能说出表面、语言和一级场景，就停止；不要机械地跑完整份清单。
  1. 示例目前位于何处：文档站点页面、API 参考、README、示例仓库/目录、博客文章、产品内帮助？其中哪些在范围内？
  2. 产品类别是什么：托管 API、SDK/库、CLI、框架、基础设施组件？
  3. 发布了哪些语言，读者最常带着哪种语言来？
  4. 目前是否有任何内容执行这些示例（测试套件、文档构建、手动检查），还是全部都是手工维护的散文？
  5. 当示例出错时，谁负责正确性：文档团队、SDK 所有者、支持人员、没有人？
  6. 这里什么会触发示例出错：SDK 发布、服务端 API 变更、认证变更、依赖漂移？
  7. 这是全新策略、对现有语料库的审计，还是两者兼有？
  8. 你能投入什么：示例能否移入经过测试的项目，有多少工程小时可用于 CI 脚手架，或者策略是否必须适用于保留在 Markdown 中的示例？
  9. 必须在什么日期之前显示出结果？
  10. 你想要一次性清理语料库，还是团队每次发布都不断执行的标准？
问题 4、8、9 和 10 决定层级排名。在分类任何内容之前先问它们。
  • Q9： 近日期会提升仅编译，后者一周内即可交付。
  • Q10： 持续执行的任务会提升采用路径上的“运行”。
  • Q4 和 Q8： 没有 CI 且没有时间构建 CI 会从菜单中删除“运行”和“仅编译”。
  • Q8： 现有的测试套件（示例可以置于其中）会直接提升“运行”。

Method

方法

Three named methods carry this work. Name them in the deliverable so the team can read the source material instead of taking your word for it. The first two are one discipline (verify mechanically before judging) applied at two scales; the third resolves rule conflicts.
Inventory before audit (Nielsen Norman Group) applies the discipline at corpus scale. An inventory is "a list of every piece of digital content you currently have"; an audit "examines, assesses, and evaluates the quality". Build the census mechanically first, then judge.
Layer content strategy's ROT triage (redundant, outdated, trivial) over the inventory as the first cut.
Docs as Tests (Manny Silva) applies it at page scale. Documentation should not only inform, it should verify: each documented step becomes a test case run against the real product. Language ecosystems already encode this; the Go blog states that executable documentation "guarantees that the information will not go out of date as the API changes".
Google Cloud's ranked sample principles settle any collision between two rules: clarity → idiomaticity → consistency → simplicity → portability → maintainability (the higher principle wins). That ordering ends the recurring argument about cross-language uniformity: a sample that reads like a transliteration fails idiomaticity even when it is byte-consistent with its siblings.
三项命名方法承载这项工作。在交付物中说出它们的名字，以便团队能够阅读原始材料，而不是听你一面之词。前两种是同一纪律（在判断之前进行机械验证）在两种规模上的应用；第三种解决规则冲突。
审计前先盘点（Nielsen Norman Group）在语料库规模上应用该纪律。盘点“列出你目前拥有的每一份数字内容”；审计“检查、评估和评价其质量”。先机械地建立统计，然后再判断。
将内容策略的 ROT 分类（冗余、过时、琐碎）分层应用于盘点作为第一刀。
文档即测试（Manny Silva）在页面规模上应用该纪律。文档不仅应当提供信息，还应当验证：每个文档化步骤都成为针对真实产品运行的测试用例。各语言生态系统已经编码了这一点；Go 博客宣称可执行文档“保证信息不会随着 API 变化而过时”。
Google Cloud 的排序示例原则解决两条规则之间的任何冲突：清晰 → 惯用 → 一致 → 简单 → 可移植 → 可维护（更高级的原则获胜）。该排序结束了关于跨语言统一性的反复争论：一个读起来像直译的示例，即使与其兄弟示例字节一致，也违背了惯用性。

Workflow

工作流

  1. Inventory the corpus. Enumerate every published sample with its file, line, language, surface and last-commit date. Run 
    scripts/sample-audit.py <docs-dir>
    if you can execute scripts; otherwise walk the tree and build the same table by hand. Nobody can set a policy for a corpus whose size they are guessing at.
  2. Triage with ROT. Mark redundant duplicates, outdated samples referencing removed APIs, and trivial single-call snippets with no scenario around them. Cutting is a legitimate outcome here.
  3. Classify each sample by execution tier (table below). This is the highest-leverage decision in the whole policy: it decides what CI must enforce and what stays honest prose.
  4. Draft the policy using ./references/sample-policy-template.md. Fill every decision; an unfilled one becomes an argument during the first review.
  5. Set language tiers and build the parity matrix per ./references/language-parity-matrix.md. Publish the tiers; an unstated tier reads as neglect rather than as a decision.
  6. Audit in two passes per ./references/audit-method.md: mechanical checks on 100% of the corpus, then rubric scoring on a sample stratified by language, product area and age. Apply ./references/audit-checklist.md per sample. Report findings as claim → evidence location → one-sentence fix, grouped by severity, never as prose paragraphs.
  7. Design verification per ./references/verification-patterns.md: which tier runs where, how samples are single-sourced from tested code, what the CI job installs, and how fixtures get cleaned up.
  8. Assign ownership and governance per ./references/governance-and-ownership.md. Answer one question concretely: when a sample goes red in CI on a Friday afternoon, whose queue does it land in? Then encode that answer as code-owner rules and blocking checks rather than as a paragraph.
  9. Rank the fix queue. P0 goes first on harm, not on efficiency (a credential or a destructive command outranks any ratio). Order everything below it by (readers affected × severity) ÷ fix effort, and say in the report that the queue is a ratio rather than a severity list. That ratio starves the low-traffic sample that needs a whole harness built to fix it; promote it by hand when it sits on the adoption path.
  10. Re-measure against the pass threshold below. Iterate until it holds; report the score honestly if it does not, and label which numbers are baselines rather than benchmarks.
  11. Record the decisions. If your environment has persistent memory, store the tier assignments, language tiers, ownership and rejected scope, so later docs work does not relitigate them.
  1. 盘点语料库。 枚举每个已发布示例及其文件、行、语言、表面和最后提交日期。如果你能执行脚本，则运行 
    scripts/sample-audit.py <docs-dir>
    ；否则手动遍历树并构建相同的表。没有人能为一个规模靠猜测的语料库设定策略。
  2. 使用 ROT 分类。 标记冗余重复、引用已移除 API 的过时示例，以及没有场景围绕的琐碎单调用片段。删除在这里是合法结果。
  3. 按执行层级对每个示例分类（见下表）。这是整个政策中影响最大的决策：它决定 CI 必须强制执行什么，以及什么保持为诚实的文字。
  4. 使用 ./references/sample-policy-template.md 起草策略。 填写每一个决定；未填写的决定在首次评审中会成为争论点。
  5. 按照 ./references/language-parity-matrix.md 设置语言层级并构建一致性矩阵。 发布层级；未说明的层级读起来像是疏忽，而不是决策。
  6. 按照 ./references/audit-method.md 进行两遍审计： 对全部语料库进行机械检查，然后按语言、产品区域和年龄分层对样本进行评分。对每个示例应用 ./references/audit-checklist.md。将发现报告为 声明 → 证据位置 → 一句话修复，按严重性分组，绝不要作为散文段落。
  7. 按照 ./references/verification-patterns.md 设计验证： 哪个层级在何处运行，示例如何从经过测试的代码单一来源，CI 作业安装什么，以及如何清理 fixtures。
  8. 按照 ./references/governance-and-ownership.md 分配所有权和治理。 具体回答一个问题：当一个示例在周五下午在 CI 中变红时，它会进入谁的队列？然后将该答案编码为代码所有者规则和阻塞检查，而不是一个段落。
  9. 排列修复队列。 P0 首先以危害为序，而不是效率（凭据或破坏性命令超越任何比率）。其下所有内容按（受影响的读者 × 严重性）÷ 修复工作量排序，并在报告中说明该队列是一个比率，而不是严重性列表。该比率会使需要构建整个脚手架来修复的低流量示例挨饿；当它位于采用路径上时手动提升它。
  10. 对照下面的通过阈值重新测量。 迭代直到达标；如果不达标，诚实地报告分数，并标记哪些数字是基线而非基准。
  11. 记录决策。 如果你的环境具有持久内存，则存储层级分配、语言层级、所有权和被拒绝的范围，以便以后的文档工作不再重新争论它们。

Execution tiers

执行层级

Every sample gets exactly one tier. The tier is a claim to the reader as much as an instruction to CI.
TierMeaningCI enforcesEngineering and upkeepReader signal
RunExecutes; documented output is assertedFull execution + output diffa standing job (fixtures, credentials, teardown, a red build every time the service moves)"This works as written"
Compile-onlyType-checks or builds, never executed (billing, destructive, third-party dependency)Build/lint onlya week to stand up, then near-zero per sample"This is valid; it was not run for you"
IllustrativePseudocode, a fragment, or a deliberate anti-patternExcludednear-zero (a visible label)Labelled on the page as not runnable
  • efficiency: compile-only > run > illustrative
  • value: run > compile-only > illustrative
  • effort: run > compile-only > illustrative
  • compliance cost: run > compile-only == illustrative
Compile-only leads because one build job catches the whole P1 class (removed symbols, missing imports, code that never compiled) for no fixtures and no credentials. Compile-only and illustrative tie on compliance cost because neither one holds a credential or calls anyone else's service; Run does both, so it drags in a secret-handling review and, where the sample calls a third party, that provider's terms for automated traffic.
Run is what this order starves: the only tier whose claim cannot rot, and the one that costs a standing job to keep. Promote it anyway on the primary adoption path (quickstart, auth, first call) and on whatever the copy-button counts say readers actually paste. Those are the samples where being wrong costs a reader their afternoon.
Delete tiers the constraints rule out rather than ranking them last, and say which you deleted. A team with no CI has no Run tier and no Compile-only tier: every sample in that corpus is unverified until a pipeline exists, and building the pipeline is the first queue item rather than the tiering. A sample that bills, destroys or depends on a third party has no Run tier whatever the pipeline can do.
This ordering is a default that shifts with who executes it. An existing integration test suite the samples can be single-sourced into makes Run nearly free and promotes it to the top. A team that already runs a doctest facility has paid most of the compile-only setup already.
Two rules keep this honest:
  • Untiered samples default to Run (a claim-assignment rule, not an investment recommendation), so that silence never becomes an excuse and an unclassified sample fails loudly.
  • Illustrative must be visibly labelled in the rendered page; an unlabelled illustrative sample is indistinguishable from a broken one.
Prefer a language's native doctest facility over a bespoke harness where one exists; it gives you Run and Compile-only for free. Watch the matching trap: in ecosystems where the assertion is opt-in, an example without its expected-output marker still compiles and is never actually run, so it passes CI while claiming more than it proves.
每个示例恰好有一个层级。层级既是对读者的声明，也是对 CI 的指令。
层级含义CI 强制执行工程与维护读者信号
运行执行；断言文档化的输出完整执行 + 输出差异一个常驻作业（fixtures、凭据、teardown、每次服务变动时构建变红）“按书面方式工作”
仅编译类型检查或构建，从不执行（计费、破坏性、第三方依赖）仅构建/静态检查一周搭建，之后每个示例接近零维护“这是有效的；没有为你运行”
示意伪代码、片段或刻意的反模式排除接近零（一个可见标签）在页面上标记为不可运行
  • 效率：仅编译 > 运行 > 示意
  • 价值：运行 > 仅编译 > 示意
  • 工作量：运行 > 仅编译 > 示意
  • 合规成本：运行 > 仅编译 == 示意
仅编译领先，因为一个构建作业就能捕获整个 P1 类（移除的符号、缺失的导入、从未编译过的代码），且无需 fixtures 和凭据。仅编译和示意在合规成本上持平，因为两者都不持有凭据或调用他人服务；运行两者都做，因此它拖入一个秘密处理审查，并在示例调用第三方时，拖入该提供商的自动化流量条款。
运行正是这个顺序所饿死的：唯一其声明不会腐坏的层级，也是需要常驻作业来维持的层级。仍然在主要采用路径（快速入门、认证、首次调用）以及复制按钮计数表明读者实际粘贴的任何内容上提升它。那些示例出错会让读者浪费整个下午。
删除约束排出的层级，而不是将它们排在最后，并说明你删除了哪些。没有 CI 的团队没有运行层级，也没有仅编译层级：该语料库中的每个示例在管道存在之前都是_未验证的_，构建管道是第一个队列项而不是分层。一个计费、销毁或依赖第三方的示例，无论管道能做什么都没有运行层级。
这个排序是一个默认值，会随执行者而改变。一个现有的集成测试套件，如果示例可以单一来源地放入其中，会使运行几乎免费并提升到顶部。一个已经运行 doctest 设施的团队已经支付了大部分仅编译设置的成本。
两条规则保持这一点诚实：
  • 未分层的示例默认归属运行（这是声明分配规则，不是投资建议），这样沉默永远不会成为借口，未分类的示例会响亮地失败。
  • 示意必须在渲染页面中可见地标记；一个未标记的示意示例与损坏示例无法区分。
优先使用语言原生的 doctest 设施，而不是定制脚手架（如果存在）；它免费为你提供运行和仅编译。注意匹配陷阱：在断言为可选加入的生态系统中，一个没有期望输出标记的示例仍然可以编译，却永远不会被实际运行，因此它通过了 CI，却声明的比证明的多。

The six policy decisions

六项策略决策

Every argument about samples reduces to one of these. Decide each explicitly:
  1. Coverage - which scenarios deserve a sample. Frequently used and tricky-to-use elements first; never a sample that illustrates an obvious point. Prefer multi-step scenarios over single-API-call snippets.
  2. Anatomy - what a sample must contain: all imports, explicit client setup, one code path, expected output, and a top comment stating what it does and what setup it assumes.
  3. Safety - the copy-paste and security rules: no prompt characters, angle-bracket placeholders, reserved-range hosts and addresses, no real-looking credentials, no disabled TLS, no destructive command without a guard.
  4. Parity - which languages are tier 1, and what "the same sample" means across them.
  5. Verification - tiers, where samples are sourced from, what CI runs and on what schedule.
  6. Ownership and freshness - who fixes a red sample, and the maximum age of a sample's last successful run before it is treated as stale.
Two rules quietly remove whole classes of defect:
  • Show one failure path for any API that fails in normal operation.
  • Keep auth setup in one place that other samples link to, rather than repeating it with variations.
关于示例的每个争论都归结为其中之一。明确决定每一项：
  1. 覆盖范围 – 哪些场景值得有示例。优先选择常用且难以使用的元素；绝不要一个说明显而易见观点的示例。更倾向于多步骤场景，而不是单 API 调用片段。
  2. 结构 – 示例必须包含什么：所有导入、显式客户端设置、一条代码路径、期望输出，以及一个顶部注释，说明它的作用以及它假设了哪些设置。
  3. 安全 – 复制粘贴和安全规则：无提示符字符、尖括号占位符、保留范围的主机和地址、无看起来真实的凭据、无不安全的 TLS 禁用、无没有保护的破坏性命令。
  4. 一致性 – 哪些语言是第 1 级，以及“同一个示例”在它们之间意味着什么。
  5. 验证 – 层级、示例来源、CI 运行什么以及按什么计划运行。
  6. 所有权和新鲜度 – 谁修复红色的示例，以及一个示例最后一次_成功运行_的最大年龄，超过则被视为过期。
两条规则悄悄移除整类缺陷：
  • 对于任何在正常操作中会失败的 API，展示一条失败路径。
  • 将认证设置放在一个地方，其他示例链接到它，而不是用不同变体重复它。

Invocation examples

调用示例

The user asksYou runYou return
"Audit the code samples in our docs"
scripts/sample-audit.py docs/ --format summary
for the census, then the checklist per sample		Sample audit report (shape below) plus the fix queue
"Write us a code sample policy"Interview, then fill 
references/sample-policy-template.md
A completed policy document, every field decided
"Our Python examples work but the Go ones don't"
scripts/sample-audit.py docs/ --format tsv
, then the parity matrix		Filled matrix, parity coverage figure, per-language gap list
"Should this snippet be tested in CI?"Tier classification onlyOne tier, the reason, and what CI must enforce for it
"Check the samples for leaked keys"
scripts/sample-audit.py docs/ --format json
, filter for the 
credential-shaped-literal
flag		P0 list, reported immediately rather than at the end
Common invocations of the script:
scripts/sample-audit.py docs/ --format summary
scripts/sample-audit.py docs/ --format json --ext .md,.mdx > inventory.json
scripts/sample-audit.py docs/ --max-lines 30 --placeholder-style angle
Treat every flag it raises as a candidate to confirm, not a verdict; a page about credential rotation legitimately contains a key-shaped string.
用户问你运行你返回
“审计我们文档中的代码示例”
scripts/sample-audit.py docs/ --format summary
用于统计，然后对每个示例使用检查表		示例审计报告（形状如下）加上修复队列
“给我们写一份代码示例策略”访谈，然后填写 
references/sample-policy-template.md
一份完整的策略文档，每个字段都已决定
“我们的 Python 示例有效，但 Go 的无效”
scripts/sample-audit.py docs/ --format tsv
，然后是一致性矩阵		填充好的矩阵、一致性覆盖率数字、每种语言的差距列表
“这个片段应该在 CI 中测试吗？”仅层级分类一个层级、原因，以及 CI 必须为其强制执行什么
“检查示例中泄露的密钥”
scripts/sample-audit.py docs/ --format json
，过滤 
credential-shaped-literal
标志		P0 列表，立即报告，而不是在最后
脚本的常见调用：
scripts/sample-audit.py docs/ --format summary
scripts/sample-audit.py docs/ --format json --ext .md,.mdx > inventory.json
scripts/sample-audit.py docs/ --max-lines 30 --placeholder-style angle
将其提出的每个标志视为需要确认的候选，而不是裁决；一个关于凭据轮换的页面合法地包含一个密钥形状的字符串。

Audit output

审计输出

Produce a short report, not a wall of findings:
undefined
生成一份简短报告，而不是一面发现墙：
undefined

Sample audit - <corpus>, <date>

示例审计 - <语料库>, <日期>

Corpus: 412 samples across 6 languages, 138 pages. Census: 380 compiled, 32 failed (92.2% pass). Secret scan: 2 findings. Rubric: 40 samples scored (stratified by language x age), mean 13.4/20. Health: 34% tested (skill baseline is 80%, not an industry standard). Findings: 11 P0, 47 P1, 190 P2.
语料库：412 个示例，6 种语言，138 个页面。 统计：380 个编译，32 个失败（92.2% 通过）。秘密扫描：2 个发现。 评分：40 个示例评分（按语言 x 年龄分层），平均 13.4/20。 健康度：34% 经过测试（技能基线为 80%，不是行业标准）。 发现：11 个 P0，47 个 P1，190 个 P2。

P0 - ship-blocking (11)

P0 - 阻断发布 (11)

docs/auth/setup.md:88 - sample embeds a live-format API key. Fix: replace with <YOUR_API_KEY> and rotate the leaked key. ...
docs/auth/setup.md:88 - 示例嵌入了实时格式的 API 密钥。 修复：替换为 <YOUR_API_KEY> 并轮换泄露的密钥。 ...

Fix queue

修复队列

  1. P0 credential leaks (11) - owner: SDK team - this week
  2. Untested quickstart path samples (9) - owner: docs - sprint ...

Severity anchors:

- **P0**: harms the reader who copies it (credential, destructive command, insecure default, data loss).
- **P1**: does not work as written (compile error, removed symbol, missing import, wrong output).
- **P2**: works but violates policy (missing tier, prompt characters, no expected output, parity gap).
  1. P0 凭据泄露 (11) - 所有者：SDK 团队 - 本周
  2. 未经测试的快速入门路径示例 (9) - 所有者：docs - 冲刺 ...

严重性锚点：

- **P0**：损害复制它的读者（凭据、破坏性命令、不安全默认值、数据丢失）。
- **P1**：按书面方式不工作（编译错误、移除的符号、缺失的导入、错误的输出）。
- **P2**：可工作但违反策略（缺失层级、提示符字符、无期望输出、一致性差距）。

Pass threshold

通过阈值

One gate has a measured comparator behind it; the rest are baselines this skill sets. Say which is which every time you report them; ./references/published-findings.md holds the citations and the circulating claims this skill refuses to repeat.
Gate with a measured comparator:
  1. Deprecated-API rate below 43%. Above it, build a deprecation-detection gate before anything else. 43% is the deprecated-API rate Zhou and Walker (FSE 2016) measured in the Stack Overflow posts they investigated; the figure is theirs, using it as a gate is this skill's choice. A governed corpus doing worse than public Q&A has a detection problem, not an authoring problem.
Skill baselines - override with the team's own data:
  1. Zero P0 findings, and 100% of samples on the primary adoption path (quickstart, auth, first call) tier Run and green in CI.
  2. Compile/run pass rate ≥90%; below that, stop new authoring and run a remediation sprint first. No vendor publishes this gate; it is a recommendation, well supported by how badly ungoverned snippet corpora do (1.00% of Stack Overflow's Java snippets compile, MSR 2016; 24.4% of public Python gists run out of the box, Gistable, ICSME 2018) but not a standard.
  3. ≥80% of the whole corpus is tier Run or Compile-only and executed by CI.
  4. Parity coverage ≥90% across tier-1 languages (tested cells ÷ scenarios × tier-1 languages), and no sample's last successful run older than the policy's freshness window.
Re-run the audit after each fix batch rather than declaring victory from the fix list. When threshold 4 cannot be met, cut samples instead of lowering the bar; a deleted sample costs a reader nothing, an untested one costs them an afternoon.
一个门禁背后有测量的比较值；其余是本技能设定的基线。每次报告时说明哪些是哪些；./references/published-findings.md 保存引用和本技能拒绝重复的流传声明。
带有测量比较值的门禁：
  1. 弃用 API 率低于 43%。 高于该值，先构建弃用检测门禁，然后再做其他任何事。43% 是 Zhou 和 Walker（FSE 2016）在调查的 Stack Overflow 帖子中测量到的弃用 API 率；该数字是他们的，将其用作门禁是本技能的选择。一个有治理的语料库表现比公开问答更差，说明存在检测问题，而不是编写问题。
技能基线 - 用团队自己的数据覆盖：
  1. 零 P0 发现，且主要采用路径（快速入门、认证、首次调用）上的 100% 示例为运行层级并在 CI 中为绿。
  2. 编译/运行通过率 ≥90%；低于该值，停止新编写并先运行一次修复冲刺。没有供应商发布此门禁；它是一个建议，得到了无治理片段语料库表现糟糕的有力支持（Stack Overflow 的 Java 片段中 1.00% 可编译，MSR 2016；公共 Python gists 中 24.4% 开箱即跑，Gistable，ICSME 2018），但不是标准。
  3. 整个语料库的 ≥80% 为运行或仅编译层级并由 CI 执行。
  4. 跨第 1 级语言的一致性覆盖率 ≥90%（已测试单元 ÷ 场景 × 第 1 级语言），且没有示例的最后一次_成功运行_早于策略的新鲜度窗口。
在每批修复后重新运行审计，而不是从修复列表宣布胜利。当无法满足阈值 4 时，应删减示例而不是降低标准；一个删除的示例对读者没有任何损失，一个未测试的示例会花费他们一个下午。

KPIs

KPI

  • Tested-sample share and parity coverage, tracked per release rather than per audit.
  • Mean time from a red CI sample to a merged fix; the real measure of whether ownership exists.
  • Support tickets or issues quoting a sample verbatim.
  • Copy-button clicks per sample, where the docs platform exposes them: high-copy samples earn tier Run first.
  • Sample age distribution: count of samples whose last successful run exceeds the freshness window.
  • Rubric score per dimension over time, not the total; the total hides which axis is failing.
  • 经过测试的示例份额和一致性覆盖率，按发布而不是按审计跟踪。
  • 从 CI 中出现红色示例到合并修复的平均时间；这是所有权是否存在的真正衡量标准。
  • 逐字引用示例的支持工单或问题。
  • 每个示例的复制按钮点击数（在文档平台公开的情况下）：高复制示例首先获得运行层级。
  • 示例年龄分布：最后一次成功运行超过新鲜度窗口的示例数量。
  • 随时间推移每个维度的评分，而不是总分；总分隐藏了哪个轴在失败。

Failure modes

失败模式

SymptomFix
Samples pass CI but fail for readersCI installs from the working tree; install the published artefact instead
Sample suite disabled after flaky failuresSplit hermetic (per-PR) from integration (scheduled); fix fixture teardown before re-enabling
Fragment cannot run because imports are elidedSingle-source from a real file and publish a marked region; hide setup, never delete it
Reader pastes a placeholder verbatimUse angle brackets and reserved-range hosts, never a plausible fake value; explain each placeholder
Same scenario behaves differently per languageFix parity by scenario and outcome, not by translating one language's code
Audit was a read-through of the top pagesCensus the whole corpus mechanically; stratify the human sample - see the negative example in 
audit-method.md
Policy written, corpus never re-auditedPut the audit in the release checklist; a policy nobody measures is a wish
Samples rewritten for style, not correctnessDelegate style to the ecosystem's formatter and linter; spend review on behaviour
Docs build stays green while samples are redFail the docs build on sample failures, or the red mark gets ignored
Owners assigned to hand-pasted MarkdownMove samples into compilable source first; ownership without a mechanism is a name on a wiki page
A quoted benchmark nobody can sourceCheck 
published-findings.md
; it lists the circulating claims this skill refuses
症状修复
示例通过 CI 但在读者处失败CI 从工作树安装；改为安装已发布的工件
示例套件在出现不稳定失败后被禁用将隔离（每个 PR）与集成（计划）分开；在重新启用前修复 fixture teardown
片段因导入被省略而无法运行从真实文件单一来源并发布标记区域；隐藏设置，但绝不删除它
读者逐字粘贴占位符使用尖括号和保留范围的主机，绝不用看似合理的假值；解释每个占位符
同一场景在不同语言中行为不同按场景和结果修复一致性，而不是翻译一种语言的代码
审计只是通读顶部页面机械地统计整个语料库；对人工样本进行分层 - 参见 
audit-method.md
中的负面示例
策略已编写，语料库从未重新审计将审计放入发布检查清单；没有人衡量的策略是一个愿望
示例因风格而非正确性被重写将风格委托给生态系统的格式化和静态检查工具；将评审时间花在行为上
文档构建保持绿色，而示例为红色在示例失败时使文档构建失败，否则红色标记会被忽略
所有者被分配给手工粘贴的 Markdown首先将示例移入可编译源码；没有机制的所有权是 wiki 页面上的一个名字
引用的基准没有人能追溯检查 
published-findings.md
；它列出了本技能拒绝的流传声明

References

参考资料

  • See ./references/sample-policy-template.md for the policy document to fill in.
  • See ./references/audit-method.md for the census/stratified method, the rubric and a negative example.
  • See ./references/audit-checklist.md for per-sample checks, severity anchors and a good/bad worked pair.
  • See ./references/verification-patterns.md for execution tiers, single-sourcing and the CI shape.
  • See ./references/language-parity-matrix.md for language tiering, the matrix and drift patterns.
  • See ./references/governance-and-ownership.md for the three ownership models, metadata-driven governance, blocking CI gates and the migration order.
  • See ./references/published-findings.md for sourced figures, self-set baselines and claims to refuse.
  • Run ./scripts/sample-audit.py to extract and mechanically lint every fenced sample in a docs tree.
  • See samber/developer-relations-skills@developer-tutorial for teaching tutorials, a primary consumer of these samples.
  • See samber/developer-relations-skills@developer-docs-structure-audit for where content belongs across a docs site.
  • See samber/developer-relations-skills@version-migration-guide for before/after samples in breaking-change guides.
  • See samber/developer-relations-skills@developer-troubleshooting-docs for the error pages a failing sample should link to.
  • See samber/developer-relations-skills@coding-agent-docs-optimization when the sample's consumer is an agent, not a human.
  • See samber/developer-platform-skills@api-reference-quality for per-endpoint reference completeness; this skill owns sample policy, testing and language parity, that one owns endpoint-level coverage.
  • 参见 ./references/sample-policy-template.md 获取需要填写的策略文档。
  • 参见 ./references/audit-method.md 获取统计/分层方法、评分标准和负面示例。
  • 参见 ./references/audit-checklist.md 获取每个示例的检查、严重性锚点和好/坏工作对。
  • 参见 ./references/verification-patterns.md 获取执行层级、单一来源和 CI 形态。
  • 参见 ./references/language-parity-matrix.md 获取语言分层、矩阵和漂移模式。
  • 参见 ./references/governance-and-ownership.md 获取三种所有权模型、元数据驱动的治理、阻塞性 CI 门禁和迁移顺序。
  • 参见 ./references/published-findings.md 获取有来源的数据、自设基线和应拒绝的声明。
  • 运行 ./scripts/sample-audit.py 提取并机械地 lint 文档树中的每个围栏示例。
  • 参见 samber/developer-relations-skills@developer-tutorial 获取教学教程，这些示例的主要消费者。
  • 参见 samber/developer-relations-skills@developer-docs-structure-audit 获取内容在文档站点中的归属。
  • 参见 samber/developer-relations-skills@version-migration-guide 获取破坏性变更指南中的前后示例。
  • 参见 samber/developer-relations-skills@developer-troubleshooting-docs 获取失败示例应链接到的错误页面。
  • 参见 samber/developer-relations-skills@coding-agent-docs-optimization 当示例的消费者是代理而不是人类时。
  • 参见 samber/developer-platform-skills@api-reference-quality 获取每个端点的参考完整性；本技能拥有示例策略、测试和语言一致性，那个技能拥有端点级覆盖率。