documentation-quality-metrics

ドキュメント品質の指標

このスキルを使って、開発者向けドキュメントの品質を評価し、実際の問いに答える指標を選びます。編集上の品質と分析、ユーザーの成果を組み合わせています。

このスキルは、特に第9章「ドキュメント品質の測定」を参考に、Docs for Developers: An Engineer's Field Guide to Technical Writing をもとにしています。また、Christopher Gales と Splunk Documentation Team による The Product Is Docs: Writing Technical Documentation in a Product Development Group の第11章「成功の測定」から、言い換えたガイダンスを加えています。書籍の文章をユーザー向けの出力にそのままコピーしないでください。出典：https://link.springer.com/book/10.1007/978-1-4842-7217-6

クイックスタート

1. guidelines.md を読み込み、必要最小限の参考資料を選びます。
2. 測定によってどの判断を支援するのかを特定します。
3. 行動を起こす前に、チームがどの程度の不確実性を減らす必要があるかを決めます。
4. 構造上の仕上げより先に、機能的な品質を監査します。
5. 品質または指標の計画を全面的に立てるには、workflows/audit-doc-quality.md を使います。
6. 単独の数値より、ベースラインと背景情報を含む指標の組み合わせを優先します。

デフォルトの出力

品質の監査や指標の設計を行う場合は、次の項目を返します。

1. 測定の問い - 指標または監査によって、どの判断を支援するのか。
2. 減らすべき不確実性 - チームがまだ把握していないことと、回答に必要な精度。
3. 機能的な品質の評価結果 - アクセシビリティ、目的、見つけやすさ、正確性、網羅性。
4. 構造上の品質の評価結果 - 明確さ、簡潔さ、一貫性。
5. 指標の計画 - 定性的および定量的なシグナル、ベースライン、担当者、制約。
6. 推奨する対応 - 修正、実験、データ収集。
7. 注意点 - 利用可能な指標だけでは証明できないこと。

目次

ニーズ	参照先
品質の側面を理解する	references/core/knowledge.md
監査と指標のルールを適用する	references/core/knowledge.md
指標の例を確認する	references/core/knowledge.md
品質監査を実施する	workflows/audit-doc-quality.md
タスクに応じて参照先を選ぶ	guidelines.md

基本方針

• 優れたドキュメントは、ユーザーの目的を達成します。
• スタイルを整える前に、機能的な品質を重視します。
• 指標は判断に必要な不確実性を減らします。数を数えるだけでは測定になりません。
• 分析と定性的な証拠を組み合わせます。どちらか一方だけでは全体像を把握できません。