docs-code-sample-standards

ドキュメントのコードサンプル標準

開発者向けドキュメントのエンジニアとして、2つの成果物を作成します。公開するすべてのコードサンプルが満たすべきルールを定めたサンプルポリシーと、既存のサンプル群をそのポリシーに照らして評価し、修正の優先順位を付けるサンプル監査です。

コードサンプルは、読者が実行するドキュメント内の唯一の要素です。文章が少し間違っていても1分ほど時間を無駄にするだけですが、サンプルが少し間違っていると、読者のコードベースに取り込まれてしまいます。

UddinとRobillardが2015年に323人のプロ開発者を対象に行った調査では、曖昧さ、不完全さ、不正確さがAPIドキュメントの最も深刻な問題として挙げられ、記録された10種類の問題のうち6種類は、明らかな障害要因と評価されました。この調査はAPIドキュメント全般を対象としていますが、サンプルではこの3つの欠陥すべてが、単に読まれるだけでなく実行されます。サンプルはページを飾るものではなく、担当者のいるテスト済みの成果物として扱ってください。

対象範囲の確認

始める前に、タスクが本当にサンプル群に関するものか確認してください。次の場合は、別のスキルに振り分けてください。

• ゼロから最初の成功までを案内するページを1つ作成するタスク → クイックスタートスキル。
• サンプルを含むチュートリアルではなく、学習用チュートリアルそのものを作成するタスク → チュートリアルスキル。
• ドキュメントサイト全体でコンテンツの配置を決める問題 → ドキュメント情報アーキテクチャスキル。
• APIリファレンスページのエンドポイントごとの網羅性を扱うタスク → APIリファレンススキル。
• 対象読者が人間ではなくコーディングエージェントである場合 → エージェントドキュメントスキル。
• レビュー対象のコードが公開サンプルではなく製品そのもののソースコードである場合 → これはコードレビューであり、ドキュメントのタスクではありません。

正確なスキル識別子については、「参考資料」セクションを参照してください。

ヒアリング

質問は一度に1つずつ行い、できる場合は選択肢を提示してください。対象となる場所、言語、ティア1のシナリオを特定できた時点で止めてください。質問リストを機械的にすべて確認する必要はありません。

メモリ：現在のタスクやプロジェクトのコンテキストに関する情報をいくつか保存してください。メモリをファイルに保存する場合は、devrel-context.mdを使用してください。別のメモリシステムが使われている場合は、そちらを使用してください。タスク情報はセクションを分けて記載してください。完了したタスクは削除してください。タスクには日付を追加し、一般的なプロジェクトコンテキストには日付を付けないでください。ヒアリングへの回答は、タスクごとに異なる場合があります。

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がなく、構築に割ける時間もない場合は、選択肢から「実行」と「コンパイルのみ」の両方を外します。
• Q8： サンプルを組み込める既存のテストスイートがある場合は、「実行」を最優先します。

方法

この作業を支える、名前の付いた方法が3つあります。チームがこちらの説明を鵜呑みにせず、元の資料を読めるよう、成果物にはその名前を記載してください。最初の2つは、同じ規律（判断を下す前に機械的に検証する）を2つの規模で適用するもので、3つ目はルールの衝突を解決します。

監査前のインベントリ作成（Nielsen Norman Group）は、コーパス規模でこの規律を適用します。インベントリとは「現在保有しているデジタルコンテンツのすべてを列挙したもの」であり、監査は「その品質を調査、評価、査定すること」です。まず機械的に全数調査を行い、その後に判断します。

最初の選別として、コンテンツ戦略における ROT トリアージ（冗長、古い、些細）をインベントリに適用します。

Docs as Tests（Manny Silva）は、ページ規模でこの規律を適用します。ドキュメントは情報を提供するだけでなく、検証も行うべきです。ドキュメントに記載された各手順をテストケースにし、実際の製品に対して実行します。言語エコシステムにはすでにこの考え方が組み込まれています。Go のブログは、実行可能なドキュメントによって「API の変更に伴って情報が古くならないことが保証される」と述べています。

2つのルールが衝突した場合は、Google Cloud の優先順位付きサンプル原則で解決します。明確さ → 慣用的な表現 → 一貫性 → シンプルさ → 移植性 → 保守性（より上位の原則を優先します）。この順序によって、言語間の統一性をめぐる繰り返しの議論に決着がつきます。翻訳調のサンプルは、ほかの言語のサンプルとバイト単位で一貫していても、慣用的な表現になっていなければ不適切です。

ワークフロー

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 に沿って2 回に分けて監査します。まずコーパスの 100% に機械的なチェックを行い、次に言語、製品領域、経過年数ごとに層別化したサンプルをルーブリックで採点します。各サンプルに ./references/audit-checklist.md を適用してください。結果は、文章の段落ではなく、重要度ごとにグループ化して「主張 → 根拠の場所 → 1 文の修正案」の形式で報告します。
7. ./references/verification-patterns.md に沿って検証方法を設計します。各ティアをどこで実行するか、テスト済みコードを単一の情報源としてサンプルをどう生成するか、CI ジョブで何をインストールするか、フィクスチャをどうクリーンアップするかを決めます。
8. ./references/governance-and-ownership.md に沿ってオーナーシップとガバナンスを割り当てます。次の問いに具体的に答えてください。金曜の午後に CI でサンプルが失敗したら、誰のキューに入るでしょうか。その答えを段落に書くのではなく、コードオーナーのルールと必須チェックに反映します。
9. 修正キューに順位を付けます。 P0 は効率ではなく、有害性を基準に最優先します（認証情報や破壊的なコマンドは、どんな比率よりも優先されます）。それ以外はすべて、「（影響を受ける読者数 × 深刻度）÷ 修正工数」の順に並べ、キューは深刻度の一覧ではなく比率に基づくものであることをレポートに明記します。この比率では、修正にハーネス全体の構築が必要な低トラフィックのサンプルが後回しになります。そのサンプルが採用までの経路上にある場合は、手動で順位を上げてください。
10. 下記の合格しきい値に照らして再測定します。 しきい値を満たすまで繰り返してください。満たせない場合はスコアを正直に報告し、どの数値がベンチマークではなくベースラインなのかを明記します。
11. 判断を記録します。 環境に永続的なメモリがある場合は、ティアの割り当て、言語ティア、オーナーシップ、却下したスコープを保存し、後のドキュメント作業で再び議論にならないようにします。

実行ティア

各サンプルには、必ず1つだけティアを割り当てます。ティアは、CIへの指示であると同時に、読者に対する約束でもあります。

ティア	意味	CIでの検証内容	エンジニアリングと保守	読者へのメッセージ
実行	実行され、ドキュメントに記載された出力が検証される	完全な実行と出力の差分検証	継続的なジョブが必要（フィクスチャ、認証情報、後処理、サービスが変更されるたびにビルドが失敗する状態）	「記載どおりに動作します」
コンパイルのみ	型チェックまたはビルドのみ行い、実行はしない（課金、破壊的な処理、サードパーティへの依存がある場合）	ビルドとリントのみ	構築に数日かかり、その後のサンプルごとの負担はほぼゼロ	「有効なコードですが、実行はしていません」
例示	疑似コード、コードの断片、または意図的なアンチパターン	対象外	ほぼゼロ（明示的なラベルを付けるだけ）	実行できないことをページ上に表示

• 効率：コンパイルのみ > 実行 > 例示
• 価値：実行 > コンパイルのみ > 例示
• 労力：実行 > コンパイルのみ > 例示
• コンプライアンスコスト：実行 > コンパイルのみ == 例示

コンパイルのみが最上位になるのは、フィクスチャも認証情報も不要で、1つのビルドジョブによってP1の問題全般（削除されたシンボル、インポート漏れ、これまで一度もコンパイルされていないコード）を検出できるためです。コンパイルのみと例示は、どちらも認証情報を保持せず、他者のサービスも呼び出さないため、コンプライアンスコストは同等です。実行はその両方を行うため、認証情報の取り扱いに関するレビューが必要になり、サードパーティを呼び出すサンプルでは、そのプロバイダーが自動トラフィックに適用する利用規約への対応も必要になります。

この順序によって最も後回しにされるのは、実行です。これは、約束が古びない唯一のティアであり、維持には継続的なジョブが必要です。それでも、主要な導入経路（クイックスタート、認証、最初の呼び出し）と、コピー用ボタンの計測から読者が実際にコピーしていると分かるサンプルには、実行を割り当ててください。これらのサンプルに誤りがあると、読者の午後が潰れてしまいます。

制約によって不可能なティアは最下位に置くのではなく削除し、どのティアを削除したのかを明記してください。CIがないチームには、実行ティアもコンパイルのみのティアもありません。そのコーパスに含まれるすべてのサンプルは、パイプラインが整備されるまで_未検証_です。まずティア分けするのではなく、パイプラインの構築を最初の作業項目にしてください。課金、破壊的な処理、またはサードパーティへの依存があるサンプルには、パイプラインで何ができても実行ティアを割り当てられません。

この順序は、誰がどのように実行するかに応じて変わるデフォルトです。サンプルを一元管理できる既存の統合テストスイートがあれば、実行のコストはほぼゼロになり、最上位に引き上げられます。すでに doctest の仕組みを運用しているチームは、コンパイルのみのセットアップに必要な作業の大部分を済ませています。

正直さを保つために、次の2つのルールを設けます。

• ティアが割り当てられていないサンプルは、デフォルトで実行とします（これは約束を割り当てるルールであり、投資の推奨ではありません）。これにより、沈黙を言い訳にできず、分類されていないサンプルは明確に問題として表面化します。
• 例示には、レンダリングされたページ上で見えるラベルを必ず付けてください。ラベルのない例示サンプルは、壊れたサンプルと見分けがつきません。

言語に標準の doctest 機能がある場合は、独自のハーネスより優先してください。実行とコンパイルのみを、追加コストなしで実現できます。対応付けにまつわる落とし穴にも注意してください。アサーションを明示的に有効にする必要があるエコシステムでは、期待される出力を示すマーカーがない例もコンパイルされるだけで、実際には実行されません。そのため、証明できる範囲を超える約束をしていても、CIを通過してしまいます。

6 つのポリシー上の判断事項

サンプルに関する議論は、すべて次のいずれかに集約されます。それぞれを明確に決定してください。

1. 網羅範囲 - どのシナリオにサンプルを用意するか。使用頻度が高く、扱いが難しい要素を優先します。明白な点を示すだけのサンプルは作成しません。単一の API 呼び出しのスニペットよりも、複数ステップのシナリオを優先します。
2. 構成 - サンプルに含めるもの：すべてのインポート、明示的なクライアントのセットアップ、1 つのコードパス、期待される出力、および実行内容と前提となるセットアップを記載した先頭のコメント。
3. 安全性 - コピー＆ペーストとセキュリティに関するルール：プロンプト文字、山括弧のプレースホルダー、予約済み範囲のホストとアドレス、実在しそうな認証情報、無効化された TLS、ガードなしの破壊的なコマンドを使用しないこと。
4. 同等性 - 第 1 層に含める言語と、「同じサンプル」の定義。
5. 検証 - ティア、サンプルのソース、CI で実行する内容とそのスケジュール。
6. オーナーシップと鮮度 - サンプルが失敗した場合の修正担当者、およびサンプルが古いと見なされるまでの最終 成功実行 からの最大経過期間。

次の 2 つのルールで、欠陥の種類を根本から減らせます。

• 通常の動作で失敗する API には、失敗するケースを 1 つ示します。
• 認証のセットアップは 1 か所にまとめ、他のサンプルからそこへリンクします。異なる形式で繰り返し記述しないでください。

呼び出し例

ユーザーの依頼	実行する内容	返す内容
「ドキュメントのコードサンプルを監査してください」	件数調査には scripts/sample-audit.py docs/ --format summary を実行し、続いて各サンプルのチェックリストを使用	サンプル監査レポート（以下の形式）と修正キュー
「コードサンプルのポリシーを作成してください」	ヒアリングを行い、その後 references/sample-policy-template.md を記入	すべての項目を決定した完成済みのポリシー文書
「Python の例は動きますが、Go の例は動きません」	scripts/sample-audit.py docs/ --format tsv を実行し、その後、同等性マトリクスを作成	記入済みのマトリクス、同等性のカバレッジ値、言語ごとの不足リスト
「このスニペットは CI でテストすべきですか？」	ティアの分類のみ	1 つのティア、その理由、および 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

フラグが検出したものは、すべて結論ではなく確認候補として扱ってください。認証情報のローテーションを説明するページには、キーのような文字列が正当に記載されていることがあります。

監査結果

調査結果を大量に並べるのではなく、短いレポートを作成してください。

## 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.

### P0 - ship-blocking (11)
docs/auth/setup.md:88 - sample embeds a live-format API key.
  Fix: replace with <YOUR_API_KEY> and rotate the leaked key.
...

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

重大度の目安：

• P0：コピーした読者に害を及ぼす（認証情報、破壊的なコマンド、安全でないデフォルト、データ損失）。
• P1：記述どおりに動作しない（コンパイルエラー、削除済みのシンボル、インポート漏れ、誤った出力）。
• P2：動作するがポリシーに違反している（ティアの指定漏れ、プロンプト文字、期待される出力がない、同等性の不足）。

合格基準

1つのゲートには測定済みの比較対象があります。それ以外は、このスキルが定めるベースラインです。報告する際は毎回、どちらに当たるかを明示してください。./references/published-findings.mdには、出典と、このスキルが繰り返すことを避けている流布した主張が記載されています。

測定済みの比較対象があるゲート：

1. **非推奨 API の割合を43%未満にする。**これを上回る場合は、何よりも先に非推奨 API 検出ゲートを構築してください。43%は、Zhou and Walker（FSE 2016）が調査したStack Overflowの投稿で測定した非推奨 API の割合です。この数値は彼らのものであり、ゲートとして使うのはこのスキルの判断です。管理されたコーパスの成績が公開Q&Aより悪い場合、問題は執筆ではなく検出にあります。

スキルのベースライン ― チーム独自のデータに合わせて調整してください：

2. P0の指摘はゼロであり、主要な導入経路（クイックスタート、認証、最初の呼び出し）にあるサンプルの100%がRunティアで、CIで成功すること。
3. コンパイル／実行の成功率が90%以上であること。これを下回る場合は、新たな執筆を止め、まず修正スプリントを実施してください。このゲートを公表しているベンダーはありません。管理されていないスニペットコーパスの成績がいかに悪いか（Stack OverflowのJavaスニペットのうちコンパイルできるのは1.00%、MSR 2016、公開Python gistのうちそのまま実行できるのは24.4%、Gistable、ICSME 2018）から十分に裏付けられた推奨事項ですが、標準ではありません。
4. コーパス全体の80%以上がRunティアまたはCompile-onlyであり、CIで実行されていること。
5. ティア1言語全体でパリティカバレッジが90%以上（テスト済みセル数 ÷ シナリオ数 × ティア1言語数）であり、ポリシーで定めた鮮度期間を最後の_成功した実行_から過ぎているサンプルがないこと。

修正リストを見て完了を宣言するのではなく、修正バッチごとに監査を再実行してください。基準4を満たせない場合は、基準を下げるのではなくサンプルを削除してください。サンプルを削除しても読者には何の負担もありませんが、テストされていないサンプルは読者の午後を奪います。

KPI

• テスト済みサンプルの割合とパリティカバレッジ。監査ごとではなく、リリースごとに追跡します。
• CIで失敗したサンプルが修正され、マージされるまでの平均時間。オーナーシップが存在するかどうかを測る実質的な指標です。
• サンプルをそのまま引用したサポートチケットや課題。
• ドキュメントプラットフォームで確認できる場合は、サンプルごとのコピーボタンのクリック数。クリック数の多いサンプルを優先してRunティアにします。
• サンプルの経過期間の分布。最後に成功した実行から鮮度期間を過ぎたサンプル数を数えます。
• 合計点ではなく、各次元のルーブリックのスコア推移。合計点では、どの軸に問題があるのかがわかりません。

失敗パターン

症状	対処
サンプルは CI を通過するが、読者の環境では失敗する	CI では作業ツリーからインストールしています。公開済みの成果物をインストールしてください
不安定な失敗の後、サンプルスイートが無効になっている	隔離されたテスト（PR ごと）と統合テスト（定期実行）に分けてください。再び有効にする前にフィクスチャのティアダウンを修正してください
インポートが省略されているため、コード断片を実行できない	実際のファイルを唯一のソースとし、範囲を示して公開してください。セットアップは隠しても、削除しないでください
読者がプレースホルダーをそのまま貼り付ける	山括弧と予約済みの範囲のホストを使い、もっともらしい偽の値は使わないでください。各プレースホルダーについて説明してください
同じシナリオでも言語によって挙動が異なる	ある言語のコードを別の言語に翻訳するのではなく、シナリオと結果に基づいて一貫性を確保してください
監査が主要なページの読み通しで終わっている	コーパス全体を機械的に調査してください。人手で確認するサンプルは層別化します。audit-method.md の否定的な例を参照してください
ポリシーを策定したものの、コーパスを再監査していない	リリースチェックリストに監査を含めてください。測定されないポリシーは単なる願望です
正確性ではなくスタイルを理由にサンプルを書き直している	スタイルはエコシステムのフォーマッターとリンターに任せ、レビューでは挙動に注力してください
サンプルが失敗しているのに、ドキュメントのビルドは成功する	サンプルの失敗時にドキュメントのビルドも失敗するようにしてください。そうしないと、失敗の印は無視されます
手作業で貼り付けた Markdown に担当者を割り当てている	まずサンプルをコンパイル可能なソースに移してください。仕組みのない担当者指定は、Wiki ページに名前を載せるだけです
出典を確認できないベンチマークの引用	published-findings.md を確認してください。このスキルが採用しない、流布している主張を一覧にしています

参考資料

• 記入するポリシー文書については、./references/sample-policy-template.md を参照してください。
• 全数調査／層化抽出法、評価基準、否定的な例については、./references/audit-method.md を参照してください。
• サンプルごとの確認項目、重大度の基準、良い例と悪い例の対比については、./references/audit-checklist.md を参照してください。
• 実行ティア、単一ソース化、CI の構成については、./references/verification-patterns.md を参照してください。
• 言語のティア分け、マトリックス、ドリフトのパターンについては、./references/language-parity-matrix.md を参照してください。
• 3 つのオーナーシップモデル、メタデータ主導のガバナンス、CI のブロッキングゲート、移行順序については、./references/governance-and-ownership.md を参照してください。
• 出典付きの数値、独自に設定したベースライン、採用を見送るべき主張については、./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 を参照してください。このスキルはサンプルのポリシー、テスト、言語間の同等性を担当し、そちらはエンドポイントレベルの網羅性を担当します。