developer-docs-planning

開発者向けドキュメントの計画

このスキルは、執筆を始める前に作成する開発者向けドキュメントを決めるために使用します。ユーザーのニーズをコンテンツの種類、範囲、概要、担当者、リリース状況、調査作業、意思決定の記録に結び付けます。

このスキルは、特に第2章「ドキュメントの計画」を中心に、『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』の内容、特に第2章「Agile」、第6章「Documentation Decisions」、第13章「Research for Technical Writers」、第14章「Scenario-driven Information Development」、第22章「Working with Product Management」から、言い換えたガイダンスを加えています。書籍の本文をユーザー向けの出力にコピーしないでください。出典：https://link.springer.com/book/10.1007/978-1-4842-7217-6

クイックスタート

1. guidelines.md を読み込み、役に立つ最小限の参考資料セットを選びます。
2. ユーザーの目標、対象読者、製品の対象範囲、リリース状況を確認します。
3. 社内組織の構造ではなく、ユーザーのタスクに基づいてコンテンツの種類を選びます。
4. 詳細な計画には workflows/create-doc-plan.md を使用します。
5. タスクが意思決定、調査、シナリオ計画、またはアジャイルとの統合に関するものであれば、専用のワークフローを使用します。
6. ドキュメントの種類、目的、担当者、信頼できる情報源、依存関係、検証方法を含む概要を出力します。

デフォルトの出力

ドキュメントを計画する際は、次の内容を返します。

1. 対象読者と目標 - ドキュメントの対象者と、達成すべきこと。
2. コンテンツの種類に関する判断 - 推奨するドキュメントと、それぞれを含める理由。
3. ドキュメントの概要 - ページまたはセクション、その目的と順序。
4. 意思決定または調査の根拠 - 確認できている証拠、前提、未解決の疑問。
5. 信頼できる情報源の一覧 - コード、API スキーマ、製品責任者、サポートデータ、または設計資料。
6. リリースとレビューの計画 - 担当者、承認、時期。
7. 未解決の疑問 - 正確なドキュメントの作成を妨げる判断事項。

目次

ニーズ	ここから始める
ドキュメントの種類を理解する	references/core/knowledge.md
計画のルールを適用する	references/core/knowledge.md
計画の例を見る	references/core/knowledge.md
ドキュメントの計画を作成する	workflows/create-doc-plan.md
ドキュメントに関する判断を行う	workflows/make-doc-decision.md
執筆前に機能を調査する	workflows/research-feature-docs.md
シナリオ主導のドキュメントを計画する	workflows/plan-scenario-docs.md
ドキュメントをアジャイル作業に統合する	workflows/integrate-docs-agile.md
タスクに応じて案内する	guidelines.md

基本方針

• コンテンツの種類は、ユーザーのタスクに基づいて選びます。
• 各ドキュメントの主な目標は1つに絞ります。
• 計画は形式的な手続きではなく、軽量なエンジニアリング成果物として扱います。
• 判断、前提、情報源の不足を早い段階で明らかにします。
• ドキュメントの計画が迷路のように感じられる場合は、製品や情報アーキテクチャが複雑すぎないか検討します。