technical-manuscript-verification

技術原稿の検証

基本的な視点

技術ノンフィクションは、著者の記憶の中だけでなく、読者の環境でも機能する必要があります。検証では、コマンドが実行できるか、設定に矛盾がないか、スクリーンショットと本文が一致しているか、リンクが有効か、安全上の境界が明確か、そして失敗したときに読者が対処できるだけの情報があるかを確認します。

このスキルは、以下の監査に使用します。

• 技術書の章やチュートリアル。
• セルフホストやインフラストラクチャのガイド。
• コードスニペット、シェルコマンド、Docker Compose ファイル、設定例、図、スクリーンショット。
• 現在のプラットフォームの動作や、バージョン固有のドキュメントに依存する主張。
• ベータ版公開前または出版前の技術的正確性。

参照先

必要な情報	参照先
検証の概念と用語	references/core/knowledge.md
監査ルールと証拠の基準	references/core/rules.md
指摘事項と検証表の例	references/core/examples.md
簡易検証チェックリスト	references/core/checklist.md
段階的な検証手順	workflows/verify-technical-manuscript.md

ワークフロー

1. 検証範囲を定める

検証が必要な項目を特定します。

• コマンドとコード。
• 設定ファイルと環境変数。
• インストールとセットアップの手順。
• スクリーンショット、図、想定される出力。
• リンクと外部参照。
• 安全性、セキュリティ、プライバシー、データ損失、コストに関する警告。

原稿が大規模な場合は、対象を絞って検証します。

2. 証拠表を作成する

技術項目ごとに、以下を記録します。

Item | Location | Assumption | Verification method | Result | Fix

確認できる項目について、もっともらしさだけを根拠にしてはいけません。

3. 実環境またはシミュレーション環境で検証する

コマンドの実行、設定のリンティング、リンクの確認、サンプルのレンダリング、一次資料の参照を優先します。実行が危険または現実的でない場合は、前提条件と、なお必要な証拠を明記します。

4. 読者へのリスク別に指摘事項を分類する

以下を優先します。

• データ損失、セキュリティ上の露出、プライバシーへの被害、取り消せない変更。
• 失敗するコマンド、または異なる出力を生成するコマンド。
• 読者の作業を妨げる前提条件の不足。
• ツールやプラットフォームの変更による、最新情報とのずれ。
• 誤解を招くスクリーンショットや図。

5. 著者が適用できる修正を提示する

具体的な変更を提案します。

• 前提条件を追加する。
• コマンドまたは設定を変更する。
• 想定される出力を追加する。
• 警告、ロールバック、またはトラブルシューティングの注記を追加する。
• 変更されやすい手順を補助リソースに移す。
• 最新のドキュメントで確認が必要な主張として明示する。

出力形式

原稿を検証する場合は、以下を返します。

1. 検証範囲と前提条件。
2. 読者へのリスクが高い順に並べた指摘事項。
3. 合格／不合格／未テストの状態を含む証拠表。
4. 原稿に対する具体的な修正。
5. 最新の一次資料による確認が必要な項目。
6. ベータ読者または専門家によるレビューで確認すべき項目。

品質基準

具体的かつ証拠に基づいて記述します。「検証済み」「可能性が高い」「未テスト」「ここでは安全にテストできない」を区別します。実際に確認していない限り、または制約を明確に示していない限り、技術的な手順が機能すると断言してはいけません。