developer-docs-drafting

開発者向けドキュメントの草稿作成

読者が要点を素早く把握し、手順に従い、内容を活用できる開発者向けドキュメントを作成するために、このスキルを使います。対象読者と計画に関する情報を、明確なページ構成と実用的な文章にまとめます。

このスキルは、Docs for Developers: An Engineer's Field Guide to Technical Writing、特に第3章「Drafting documentation」を基にしています。Christopher Gales と Splunk Documentation Team による The Product Is Docs: Writing Technical Documentation in a Product Development Group、特に第9章「Learning Objectives」、第14章「Scenario-driven Information Development」、第25章「Writing SaaS Documentation」からの、言い換えたガイダンスを加えています。書籍の文章をユーザーへの出力にそのままコピーしないでください。出典：https://link.springer.com/book/10.1007/978-1-4842-7217-6

クイックスタート

1. guidelines.md を読み込み、役立つ最小限の参照資料を選びます。
2. 対象読者、ドキュメントの種類、読者が達成したい主な目標を1つ確認し、可能であれば学習目標も確認します。
3. 草稿を作成する前にアウトラインを作ります。アウトラインはドキュメントの疑似コードとして扱います。
4. ページ全体の草稿には workflows/draft-developer-doc.md を使います。
5. 最も重要な情報を先に示し、ページを素早く読み取れるようにします。

デフォルトの出力

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

1. タイトル - 読者の目標に沿ったもの。
2. 冒頭の概要 - 読者が達成できることと前提条件。
3. 構造化された本文 - 必要に応じて、見出し、手順、概念、例、リスト、注記を含めます。
4. シナリオまたは進め方 - 実際の利用経路、対象範囲の境界、または必要に応じて独立したトピックの概要。
5. 確認方法または期待される結果 - タスクが成功したことを読者が確認する方法。
6. 次のステップ - 次に進むべき場所。
7. 草稿に関する注記 - 仮定、TODO、または確認が必要な出典の詳細。

目次

ニーズ	参照先
草稿作成の要素を理解する	references/core/knowledge.md
草稿作成のルールを適用する	references/core/knowledge.md
修正前後の例を見る	references/core/knowledge.md
ページの草稿を作成する	workflows/draft-developer-doc.md
タスク別の参照先を確認する	guidelines.md

基本方針

• 読者が次に判断または実行することを意識して書きます。
• ざっと読むだけでも理解できるページにします。
• 手順は実行可能で、結果を確認できるものにします。
• シナリオ形式のドキュメントでは、製品の機能ではなく、ユーザーの問題から始めます。
• テンプレートは白紙から書き始める負担を減らすために使い、すべてのドキュメントを同じ形式に押し込みません。