developer-docs-technical-research

開発者向けドキュメントの技術調査

開発者向けドキュメントの計画や執筆に先立って、製品の動作を調査する際にこのスキルを使用します。仕様、コード、プロトタイプ、チケット、SME、実機テストから、出典を追跡できる調査メモを作成します。

このスキルは、Christopher Gales と Splunk Documentation Team による The Product Is Docs: Writing Technical Documentation in a Product Development Group のガイダンスを言い換えた内容に基づいています。特に、第13章「技術ライターのための調査」、第16章「技術的な検証」、第19章「エンジニアとの協業」、第22章「プロダクトマネジメントとの協業」を参考にしています。書籍の文章をユーザー向けの出力に転載しないでください。出典：https://link.springer.com/book/10.1007/978-1-4842-7217-6

クイックスタート

1. guidelines.md を読み込み、必要最小限の参考資料を選びます。
2. ドキュメントに関する質問、対象読者、機能、リリースの状況、リスクを明確にします。
3. コード、製品の画面や機能、仕様、チケット、SME、QA、サポート、既存ドキュメントから情報源マップを作成します。
4. 機能の動作やユーザーへの影響が不明確な場合は、workflows/research-feature-docs.md を使用します。
5. 主な作業がSMEから事実を聞き出すことである場合は、workflows/interview-doc-sources.md を使用します。
6. 検証済みの事実、前提、矛盾、情報源の担当者、未解決の質問を提示します。

デフォルトの出力

ドキュメント調査を実施した際は、次の内容を返します。

1. 調査概要 - ドキュメントに関する質問、対象読者、範囲、必要な判断。
2. 検証済みの事実 - 動作、制限、デフォルト値、前提条件、権限、エラー、例とその出典。
3. ユーザーへの影響 - 読者が実行、判断、リスクにさらされる、または誤解する可能性のある内容。
4. 情報源マップ - 重要な事実それぞれの信頼できる担当者または成果物。
5. 矛盾と不足事項 - 未解決の意見の相違、アクセス不足、未テストの動作。
6. 推奨するドキュメント対応 - 計画、下書き、延期、製品課題の起票、レビュー依頼。

目次

必要な内容	参照先
技術調査の概念を理解する	references/core/knowledge.md
機能調査計画を作成する	workflows/research-feature-docs.md
エンジニア、PM、QA、サポート、またはフィールドチームにインタビューする	workflows/interview-doc-sources.md
タスクや症状に応じて参照先を決める	guidelines.md

基本方針

• 実装だけでなく、ユーザーへの影響を調査します。
• 製品、API、CLI、UI、または環境を利用できる場合は、直接検証します。
• 担当者として明示された人や、長期的に参照できる成果物を信頼できる情報源として扱います。
• 不確実性は解消されるまで明示します。
• ドキュメントで回避可能な混乱を説明せざるを得ない場合は、製品またはUXの不具合を起票します。