技術ドキュメント作成

学べること

• コード、仕様、または大まかなメモから高品質な技術ドキュメントを生成するためのClaude活用方法
• 異なる読者向けに技術的な深さを調整するテクニック
• 大規模なドキュメントプロジェクト全体で一貫性と構成を維持する方法

ユースケース

技術ドキュメントは、ソフトウェア開発で最も普遍的に軽視されている部分の一つです。良いドキュメントが重要なことは誰もが知っています——サポートの負担を減らし、オンボーディングを加速し、オープンソースプロジェクトを実際に使えるものにします。しかし、ドキュメントは書くのが難しく、後回しにしやすく、コードが進化するにつれて維持するのが辛い作業です。

Claudeはドキュメント作業に非常に適しています。コードを読んで何をするかを理解し、技術的な概念を平易な言語に翻訳し、一貫したフォーマットで構造化された文章をオンデマンドで生成できるからです。以前はドキュメント作業を恐れていた開発者も、数分でコードベースから最初の草稿を生成し、包含すべきもの、適切な詳細レベル、実際に役立つ例はどれかという人間の判断の部分にエネルギーを注ぐことができます。

このガイドでは、3つの一般的なドキュメントシナリオに焦点を当てます：README（あらゆるプロジェクトの玄関口）、APIリファレンスドキュメント（パブリックインターフェースの関数ごとのカバレッジ）、およびユーザーガイド（エンドユーザー向けのタスク指向のウォークスルー）。これらのテクニックは、マイナーな調整で他の形式——チュートリアル、ランブック、アーキテクチャ決定記録——にも適用できます。

ステップバイステップガイド

ステップ1：ドキュメントの読者と目的を定義する

Claudeにコードやドキュメント化するコンテンツを提供する前に、二つのことを明確にしましょう：

読者は誰か？ 選択肢は幅広いです：初めてライブラリを評価する開発者、既存のコードベースにオンボードするチームメンバー、タスクを達成しようとしているノンテクニカルなユーザー、特定のパラメータを調べている経験豊富なユーザー。各読者には異なる説明レベル、異なる前提知識、異なる重点が必要です。

読者は何をしようとしているか？ ドキュメントは特定の役割を果たします：「このライブラリを使うかどうかを評価する」、「初めてインストールして実行する」、「特定の関数の動作を調べる」、「何かが機能していない理由をトラブルシューティングする」など。コードの構造ではなく、読者の役割を中心にドキュメントを構成しましょう。

このコンテキストをClaudeに明示的に提供してください。アウトプットの読み方がまったく変わります。

ステップ2：Claudeにソース素材を提供する

Claudeはいくつかの種類のソース素材で作業できます：

• コード直接 — 関数、クラス、モジュール、またはファイル全体を貼り付けます。Claudeはコードを読んで動作、パラメータ、戻り値、潜在的なエッジケースを推測できます。
• 既存の大まかなドキュメント — メモ、草稿、またはコードのコメントを貼り付けます。Claudeはそれを拡張、再構成、ポリッシュできます。
• 口頭での説明 — システムが何をするかを平易な言語で説明します。Claudeはドキュメントのスケルトンを生成し、あなたが詳細を追加します。
• 仕様や要件 — 設計ドキュメントや仕様を貼り付けます。Claudeはその仕様に沿ったドキュメントを生成できます。

複雑なAPIについては、すべてを一度に投入するのではなく、エンドポイントや関数を一つずつ処理しましょう。これにより、より正確で焦点が絞られたドキュメントが生成されます。

ステップ3：ドキュメント形式を指定する

異なるドキュメントタイプには確立された慣例があります。どの形式に従うかをClaudeに伝えましょう：

• README：標準セクション——何をするか、なぜ有用か、インストール、クイックスタート、設定、貢献、ライセンス。
• APIリファレンス：エンドポイント/関数ごとに一つのセクション——説明、パラメータ（名前、型、必須/オプション、説明）、戻り値、リクエスト/レスポンスの例、エラーコード。
• ユーザーガイド：タスク指向——番号付きステップ、警告とメモのコールアウト、括弧内に説明されたスクリーンショット（後で実際のスクリーンショットを追加）、各ステップの期待される結果。
• 概念的な概要：なぜに焦点——解決している問題、メンタルモデル、パーツがどのように組み合わさるか、これと代替案をいつ使うか。

ステップ4：技術的な正確さと明確さを反復的に改善する

Claudeの最初の草稿は構造的に良いですが、特にコードから動作を推測している場合は技術的な不正確さを含む可能性があります。すべての技術的主張をレビューしましょう：

• パラメータの名前と型は正確か？
• 説明されている動作は実際にコードが行うことか？
• エラーコードとエラーメッセージは正確か？
• 例は実際に機能するか？

エラーを具体的に修正してください：「timeoutパラメータはオプションで、必須ではなくデフォルトは30秒です。それを修正して例を更新してください。」

読者の視点から明確さについてもレビューしましょう：「ステップ2の認証の説明は、読者がすでにAPIキーを持っていることを前提としています。取得方法を説明するメモを追加してください。」

ステップ5：例とコードサンプルを生成する

優れたドキュメントは例によって成功するかどうかが決まります。常にClaudeにコードサンプルを別途、文章よりも重点を置いて生成するよう依頼しましょう：

「このAPIリファレンスの各関数について、Pythonで完全で実行可能なコード例を生成してください。例は最小限のおもちゃの例ではなく、最も一般的な実際のユースケースを示すべきです。インポート文と必要な設定を含めてください。」

コード例はコピー＆ペーストで使えるものであるべきです。実際の値（APIキーなど）を置き換える必要がある場合は、明確にマークされたプレースホルダーを使いましょう：key123ではなくYOUR_API_KEY_HERE。

プロンプトテンプレート

技術ドキュメントを書く必要があります。コンテキストは以下の通りです：

**ドキュメントタイプ**：[README / APIリファレンス / ユーザーガイド / チュートリアル / ランブック]
**プロジェクト名**：[プロジェクトまたはツールの名前]
**何をするか**：[1〜2文の説明]
**ターゲット読者**：[誰が読むか？彼らの技術レベルと役割は？]
**読者の役割**：[読者はこのドキュメントで何を達成しようとしているか？]
**形式の慣例**：[従うべき特定の形式、例：「OpenAPIスタイル」または「StripeスタイルのAPIドキュメント」]

以下のソース素材のドキュメントを生成してください：

---
[コード / 仕様 / 大まかなメモをここに貼り付けてください]
---

各セクションについて：
- 初めて見る人向けに書く
- 動作について不確かな場所には[VERIFY]とフラグを立てる
- 主要な概念ごとに少なくとも一つのコード例を含める
- この読者にとって必要最小限の技術的専門用語を使う

ヒントとベストプラクティス

1. 擬似コードではなく実際のコードを貼り付ける — Claudeはコードの説明よりも実際のコードから劇的に正確なドキュメントを生成します。関数が何をするかを言い換えないでください——関数を貼り付けましょう。Claudeは説明から正確な詳細を作り出すよりも、はるかに頻繁にそれを正しく読み取ります。

2. Claudeに自身の不確かさにフラグを立てるよう依頼する — すべてのドキュメントプロンプトにこれを追加しましょう：「コードから直接読み取るのではなく動作を推測している場合は、そのセクションを[INFERRED]とマークしてください。公開前にこれらを確認します。」これにより自信ありげに聞こえるが誤っているドキュメントを防ぎます。

3. whatだけでなくwhyも文書化する — コードは何が起きるかを説明します。ドキュメントはなぜを説明すべきです：この設計判断がなされた理由、代替案よりこの関数をなぜ使うか、このパラメータが存在する理由。定期的にClaudeに依頼しましょう：「このAPIの各主要設計決定について、簡単な『これが機能する理由』メモを追加してください。」

4. ドキュメントスタイルガイドのプロンプトを保持する — 大規模なプロジェクトを文書化する場合、一貫性が重要です。慣例を一度定義し（物のネーミング方法、二人称か三人称か、警告とメモのフォーマット方法）、このスタイルガイドをすべてのドキュメントセッションの最初に貼り付けましょう。

5. Claudeを使って既存のドキュメントを監査する — ClaudeにコードとそのClaudeが読み取れる既存ドキュメントを提供し、「これを読んだ後に新しい開発者が持つが答えられていない質問は何か？不明確な点は？不足しているものは？」と尋ねましょう。これにより、自分でドキュメントを読み直すよりはるかに速く、ターゲットを絞ったギャップのリストが生成されます。

試してみよう

ドキュメントのない関数、モジュール、またはスクリプトを見つけてください。個人プロジェクト、ユーティリティスクリプト、または職場のコードベースの何かかもしれません。

コードを上のプロンプトテンプレートとともにClaudeに貼り付け、読者を「このコードベースを見たことのない開発者」に設定し、READMEまたは関数レベルのドキュメントを依頼しましょう。

技術的な不正確さについてアウトプットをレビューし（おそらく1、2か所あるでしょう——会話の中で修正してください）、新鮮な目でその結果を見てください：これはあなたが類似のライブラリを初めて見たときに存在してほしかったドキュメントか？そうでなければ、不足しているものをClaudeに伝えてください。あなたが考えていたよりも速くそのレベルに到達するでしょう。