technical-writing

テクニカルライティング

このスキルを使うと、AI エージェントは API リファレンス、ユーザーガイド、入門チュートリアル、変更履歴、アーキテクチャ決定記録など、さまざまな形式で質の高い技術ドキュメントを作成できます。エージェントは対象読者を分析し、情報を論理的に構成し、一貫した書式基準を適用して、すべてのドキュメントが正確で読みやすく、実際の行動に役立つものになるようにします。

ワークフロー

1. ドキュメントの種類と対象読者を特定する 必要なドキュメントの種類（API リファレンス、チュートリアル、ユーザーガイド、変更履歴、アーキテクチャドキュメント）と、読む人（初心者の開発者、経験豊富なエンジニア、エンドユーザー、関係者）を特定します。それに応じて、語彙、詳しさ、前提とする知識を調整します。初心者向けのチュートリアルでは各手順を説明し、上級エンジニア向けの API リファレンスでは簡潔かつ正確に記述します。

2. 資料を収集する ソースコード、既存のドキュメント、設計資料、ユーザーストーリー、API スキーマ（OpenAPI/Swagger）、コミット履歴、関係者へのインタビューなど、関連する入力情報をすべて収集します。正確性を確保するために、それぞれの情報の信頼できる出典を特定します。確認が必要な情報の不足があれば記録します。

3. ドキュメントの構成を設計する ドキュメントの種類に応じた慣例に従って、アウトラインを作成します。API リファレンスでは、各エンドポイントに一貫したテンプレートを使います。チュートリアルでは、手順を順を追って説明します。アーキテクチャドキュメントでは、決定記録の形式（コンテキスト、決定、結果）に従います。コード例、表、コールアウトボックスを配置する場所を計画します。

4. 内容を書く 明確で直接的な表現を使ってドキュメントの草稿を作成します。能動態と短い文を優先します。各セクションの冒頭で、最も重要な情報を伝えます。読者がコピーして実行できる、完全で実行可能なコード例を含めます。一貫した用語を使い、略語は初出時に定義します。選択した標準（Markdown、reStructuredText、AsciiDoc）に従って書式を整えます。

5. ナビゲーションと相互参照を追加する 長いドキュメントには目次を挿入し、関連するセクション間にはアンカーリンクを追加します。また、前提となるドキュメントや関連する補足ドキュメントへのリンクも追加します。チュートリアルの最後には「次のステップ」セクションを加えます。

6. 正確性と完全性を確認する すべてのコード例が正しくコンパイルまたは実行できることを確認します。API エンドポイントのパス、パラメーター、レスポンススキーマが実際の実装と一致していることを確認します。チュートリアルの各手順で、説明どおりの結果が得られることを確認します。プレースホルダーテキストや TODO 項目が残らないようにします。

使用方法

エージェントに次の情報を提供します。

• ドキュメントの種類 — API リファレンス、チュートリアル、ユーザーガイド、変更履歴、アーキテクチャ決定記録、README
• 対象 — ドキュメント化する機能、API、ツール、またはシステム
• 対象読者 — 想定読者のスキルレベルと役割
• 資料 — コードファイル、スキーマ、設計ドキュメント、または機能の説明
• 形式 — Markdown、reStructuredText、AsciiDoc、または HTML

プロンプトの例：「/users エンドポイントの API リファレンスを作成してください。対象読者はサードパーティの開発者です。OpenAPI 仕様は次のとおりです：[添付ファイル]」

例

例 1：API エンドポイントリファレンス

入力：「POST /api/v1/webhooks エンドポイントを文書化してください。Webhook サブスクリプションを作成します。Bearer トークン認証が必要です。本文：url（string、必須）、events（string[]、必須）、secret（string、任意）。201 または 422 を返します。」

出力：

POST /api/v1/webhooks

新しい Webhook サブスクリプションを作成します。Authorization ヘッダーに Bearer トークンが必要です。

フィールド	型	必須	説明
url	string	はい	ペイロードを受信する HTTPS エンドポイント URL です。
events	string[]	はい	サブスクライブするイベントの種類です（例：["order.created"]）。
secret	string	いいえ	HMAC-SHA256 署名シークレットです。省略すると自動生成されます。

curl -X POST https://api.example.com/api/v1/webhooks \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://myapp.com/hooks","events":["order.created"]}'

201 Created： {"id":"wh_9a8b7c6d","url":"https://myapp.com/hooks","events":["order.created"],"active":true}

422 エラー： {"error":{"code":"validation_error","details":[{"field":"url","message":"URL must use HTTPS."}]}}

例 2：スタートガイドチュートリアル

入力：「Python SDK（acme-sdk）のスタートガイドチュートリアルを作成してください。インストール、認証、プロジェクトの一覧表示を説明します。」

出力：

Acme Python SDK を使い始める

前提条件

• Python 3.9 以降と Acme API キー（Settings > API Keys で確認できます）

ステップ 1：SDK をインストールする

pip install acme-sdk

ステップ 2：API キーを設定する

export ACME_API_KEY="sk_live_your_key_here"

ステップ 3：プロジェクトを一覧表示する

import os
from acme_sdk import AcmeClient

client = AcmeClient(api_key=os.environ["ACME_API_KEY"])
for project in client.projects.list():
    print(f"{project.id}: {project.name}")

出力例：

proj_abc123: My First Project
proj_def456: Marketing Site

次のステップ

• プロジェクトを作成する（プログラムから）
• Webhook を設定する（リアルタイムイベント用）

ベストプラクティス

• まず行動を示します。 各セクションは背景情報ではなく、読者が行う必要のあることから始めます。説明は指示の後に記載します。
• 完全で実行可能なコードを用意します。 コード例はすべて、コピーするだけで動作するようにします。インポート、変数宣言、期待される出力を含めます。
• 一貫したテンプレートを使用します。 API リファレンスでは、すべてのエンドポイントで同じ構成に従います。チュートリアルでは、全体を通して同じステップ形式にします。
• すばやく確認できる内容にします。 見出し、表、箇条書き、コードブロックを使用して、読者がすべての段落を読まなくても情報をすばやく見つけられるようにします。
• ドキュメントをバージョン管理します。 ドキュメントを特定のソフトウェアバージョンに対応付けます。機能が導入されたバージョンや API が非推奨になったバージョンを明確に示します。
• 手順をテストします。 チュートリアルのすべてのステップを実際に試し、説明どおりの結果になることを確認します。

エッジケース

• 文書化されていない動作： ソースコードから、仕様に記載されていない動作が判明した場合は、「現在の動作」として文書化し、意図した動作かどうかを確認するようエンジニアリングチームに知らせます。
• 1 つのドキュメントに複数の対象読者がいる場合： 段階的な構成にします。最初に必須事項を示し、「上級者向け」セクションを展開できるようにするか、詳細なドキュメントへのリンクを掲載します。
• 頻繁に変更される API： バージョンまたは日付を目立つように記載し、インターフェースが変更される可能性があることを免責事項として含めます。
• ソース資料の不足： 不足している情報を明示的に列挙し、推測するのではなく提供を依頼します。
• 英語以外のドキュメント： 英語の慣習をそのまま翻訳するのではなく、その言語の開発者コミュニティにおける技術文書の慣習に従います。