technical-documentation

技術ドキュメント作成の方法論

技術ドキュメントは、ツールとユーザーをつなぐインターフェースです。この方法論では、読者の疑問に答え、読者の妨げにならず、プロジェクトの進化に合わせて保守しやすいドキュメントの作成方法を説明します。

テクニカルライターの担当範囲

担当すること	担当しないこと
API ドキュメント — エンドポイントのリファレンス、パラメーター、例	編集部門が担当する編集記事や長文コンテンツ — このスキルの対象外です
README の作成 — プロジェクト概要、クイックスタート、設定	ブランドメッセージやマーケティングコピー — ブランドデザイナーの担当です
CLI ドキュメント — ヘルプテキスト、使用方法、終了コード	コードアーキテクチャの決定 — software-architecture-analysis の担当です
エージェント向けドキュメント — AGENTS.md、スキルのドキュメント	プロジェクトのロードマップや製品ビジョン — プロダクトマネージャーの担当です
リファレンスドキュメント — 設定ファイル、トラブルシューティング、アーキテクチャ	パフォーマンス最適化のガイダンス — systematic-debugging / SRE の担当です
ドキュメントサイトの構成 — 情報アーキテクチャ、相互参照、検索	コードの品質と標準 — qa-methodology / QA エンジニアの担当です

参照ファイル

参照先	読み込むタイミング
references/readme-patterns.md	README の作成や再構成を行うとき — すべての README に必要なセクション、クイックスタートのパターン、インストール方法のバリエーション、設定のドキュメント
references/api-documentation-cli-help.md	API のドキュメント作成（エンドポイントの構成、パラメーターの規則、例の設計、認証パターン、OpenAPI アノテーション）や CLI ヘルプテキストの設計（使用方法の行、フラグ、終了コード、サブコマンドの階層、man ページ）を行うとき
references/agent-facing-docs.md	AGENTS.md やスキルのドキュメントを作成するとき — トリガーパターン、読み込み順序、出力の契約、相互参照
references/information-architecture.md	ドキュメントサイトを構成するとき — 段階的な情報開示、相互参照、検索の最適化、保守戦略

関連スキル

• documents — ドキュメントの内容からオフィス形式の成果物（PDF、Word、Excel、PowerPoint）を作成します。ドキュメントサイトとマークアップの規則は引き続きこのスキルの対象です。

基本原則

実装ではなくインターフェースをドキュメント化する — ユーザーが知る必要があるのは、関数の動作、受け取るもの、返すものです。内部でどのように動作するかはソースコードで確認できます。

優れたドキュメントは読者の疑問に答える — 読者によって疑問は異なります。使い始めるには？リファレンスは？トラブルシューティングは？それぞれの読者がすばやく答えにたどり着けるように、ドキュメントを構成します。

物語の展開より網羅性を優先する — 技術ドキュメントは記事ではありません。読者は必要な箇所に飛んで読みます。すべてのパラメーター、すべてのエッジケース、すべてのエラーコードを網羅します。退屈な部分も省略しないでください。そうした部分こそ、読者が必要とする情報です。

すべてのドキュメントには保守の負担が伴う — 作成したページはすべて保守が必要です。品質を下げてすべてを記載するより、範囲を絞って内容を充実させることを優先します。保守コストはドキュメントの範囲に比例します。

説明するだけでなく、実例を示す — すべての概念に実際に動かせる例が必要です。すべての API エンドポイントにリクエストとレスポンスが必要です。すべての設定オプションに、説明だけでなく完全な例が必要です。

移植性

このスキルは、特定のホスト環境に依存しないよう意図的に設計されています。ここに記載されている参照資料、テンプレート、スクリプトの読み込みには、エージェントの通常の方法を使用してください。特定のプロファイルシステム、タスクオーケストレーター、メモリーサービス、レスポンス引き継ぎ形式を前提にしないでください。