developer-docs-editing-review

開発者向けドキュメントの編集レビュー

草稿ができた後に開発者向けドキュメントを改善するには、このスキルを使用します。編集を検証とリファクタリングとして捉え、ドキュメントの正確性、完全性、構成、明瞭さ、簡潔さ、レビューのしやすさを確認します。

このスキルは、Docs for Developers: An Engineer's Field Guide to Technical Writing、特に第4章「ドキュメントの編集」を基にしています。また、Christopher Gales と Splunk Documentation Team による The Product Is Docs: Writing Technical Documentation in a Product Development Group、特に第15章「技術編集」と第16章「技術検証」のガイダンスを、言い換えて追加しています。書籍の文章をそのままユーザー向けの出力にコピーしないでください。出典：https://link.springer.com/book/10.1007/978-1-4842-7217-6

クイックスタート

1. guidelines.md を読み込み、必要最小限の参考資料を選びます。
2. ドキュメントの種類、対象読者、信頼できる情報源、リリースリスクを特定します。
3. 技術的な正確性、完全性、構成、明瞭さ、簡潔さを個別のパスで確認します。
4. 手順、移行、セキュリティ、データ、本番環境の変更について正式な検証が必要な場合は、workflows/verify-technical-doc.md を使用します。
5. 全体を編集する場合は、workflows/edit-developer-doc.md を使用します。
6. レビューを求められた場合は、まず指摘事項を返します。編集を求められた場合は、改訂したテキストを返します。

デフォルトの出力

ドキュメントをレビューする場合は、以下を返します。

1. 指摘事項 - 読者へのリスクが高い順に並べ、可能であればファイルやセクションを示します。
2. 未実施の検証 - 確認していないコマンド、例、スクリーンショット、API に関する事実、出典の主張。
3. 検証の進め方 - セルフテスト、専門分野の担当者によるレビュー、QA テスト、またはリリースブロッカー。
4. 推奨する編集 - 具体的な変更または書き換え。
5. レビューの依頼先 - 技術的な詳細を検証する担当者。
6. 残存リスク - 編集後も残る前提。

直接編集する場合は、改訂したドキュメントに、簡潔な変更概要と未解決の質問を添えて返します。

目次

必要な作業	まず確認する箇所
編集パスを理解する	references/core/knowledge.md
レビュー規則を適用する	references/core/knowledge.md
編集とフィードバックの例を確認する	references/core/knowledge.md
全体を編集する	workflows/edit-developer-doc.md
リスクの高い技術ドキュメントを検証する	workflows/verify-technical-doc.md
タスクに応じた進め方を確認する	guidelines.md

基本方針

• 執筆と編集を分けます。未検証の欠陥を放置したまま、表現を整えないでください。
• 文体の好みより、読者に影響する誤りを優先します。
• 適切な技術担当者に、具体的なレビューを依頼します。
• リスクの高い手順は、検証されるか、リスクが明示的に受け入れられるまでリリースブロッカーとして扱います。
• フィードバックは、レビュー担当者の立場やコメント数ではなく、ユーザーのニーズに基づいて反映します。