documentation

ドキュメント

このスキルは、API ドキュメント、テクニカルライティング、変更履歴の生成、開発者ガイドなど、包括的なドキュメント作成機能を提供します。OpenAPI 仕様からユーザー向けの変更履歴まで、あらゆる内容を扱います。

このスキルを使用する場面

• REST API や GraphQL スキーマをドキュメント化するとき
• OpenAPI/Swagger 仕様を作成するとき
• クライアント SDK を生成するとき
• API 統合ガイドを作成するとき
• インタラクティブな API ドキュメントを作成するとき
• API のバージョン管理や移行ガイドを保守するとき
• ユーザーガイドやチュートリアルを作成するとき
• README ファイルを作成または改善するとき
• アーキテクチャや設計上の決定をドキュメント化するとき
• コードコメントやインラインドキュメントを作成するとき
• コンテンツの明瞭さやアクセシビリティを改善するとき
• はじめに向けたドキュメントを作成するとき
• 機能仕様書や設計ドキュメントを作成するとき
• アーキテクチャ決定記録（ADR）を作成するとき
• 技術的な決定とその根拠をドキュメント化するとき
• バージョンアップ用の移行ガイドを作成するとき
• 破壊的変更とアップグレード手順をドキュメント化するとき
• データベース移行を計画し、ドキュメント化するとき
• 新バージョンのリリースノートを準備するとき
• 週次または月次の製品アップデート概要を作成するとき
• 顧客向けの変更内容をドキュメント化するとき
• アプリストアへの提出用に変更履歴を作成するとき
• アップデート通知を生成するとき
• 社内向けのリリースドキュメントを作成するとき
• 公開されている変更履歴／製品アップデートページを保守するとき

このスキルでできること

1. OpenAPI 仕様：完全な OpenAPI 3.0/Swagger 仕様を作成します
2. SDK 生成：クライアントライブラリと SDK を生成します
3. インタラクティブなドキュメント：Postman コレクションとインタラクティブなドキュメントを作成します
4. バージョン管理：API のバージョン管理と移行ガイドを管理します
5. コード例：複数の言語で例を提供します
6. 開発者ガイド：認証ガイドと統合ガイドを作成します
7. ユーザーガイド：明確な手順を含む、ステップごとのユーザーガイドを作成します
8. チュートリアル：知識を段階的に深められるチュートリアルを作成します
9. README ファイル：バッジやセクションを含む包括的な README ファイルを作成します
10. アーキテクチャドキュメント：システムアーキテクチャと設計上の決定をドキュメント化します
11. コードドキュメント：明確なコードコメントとインラインドキュメントを作成します
12. コンテンツの構成：明確な見出しと流れに沿ってコンテンツを構成します
13. 変更履歴の生成：Git のコミットをユーザーにわかりやすい変更履歴に変換します
14. 設計仕様書：機能仕様書と技術設計ドキュメントを作成します
15. ADR：背景と影響を含むアーキテクチャ決定記録をドキュメント化します
16. 移行ガイド：ロールバック手順を含む、ステップごとの移行ドキュメントを作成します

使用方法

API をドキュメント化する

Create OpenAPI specification for this API

Generate API documentation for the /api/users endpoints

ドキュメントを作成する

Create a user guide for this feature

Write a README for this project

変更履歴を生成する

Create a changelog from commits since last release

Generate changelog for all commits from the past week

API ドキュメント

開発しながらドキュメントを作成する

• 開発後ではなく、開発中に API をドキュメント化します
• ドキュメントをコードと同期させます
• 抽象的な説明より実際の例を使います
• 成功時とエラー時の両方のケースを示します
• ドキュメントを含め、すべてをバージョン管理します

OpenAPI 仕様

構成：

• API メタデータ（タイトル、バージョン、説明）
• サーバー定義
• セキュリティスキーム
• パスとオペレーション
• リクエスト／レスポンスのスキーマ
• すべてのオペレーションの例

例：

openapi: 3.0.0
info:
  title: User API
  version: 1.0.0
  description: API for user management

paths:
  /users:
    get:
      summary: List users
      responses:
        '200':
          description: List of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'

SDK 生成

対応言語：

• JavaScript/TypeScript
• Python
• Java
• Go
• Ruby
• PHP

ツール：

• OpenAPI Generator
• Swagger Codegen
• SDK ジェネレーター

コード例

複数の言語で例を提供します。

• JavaScript/Node.js
• Python
• cURL
• Ruby
• Java

テクニカルライティング

読者に合わせて書く

• 読者のスキルレベルを把握します
• 適切な用語を使います
• 必要に応じて背景情報を提供します
• 事前知識は最小限と想定します
• トラブルシューティングのセクションを含めます

成果から始める

• ユーザーが何を達成できるのかを最初に示します
• 手順より先に価値を伝えます
• 明確で、行動につながる言葉を使います
• 機能ではなく、ユーザーの成功に焦点を当てます

能動態を使う

• 受動態より能動態を優先します
• 明確で簡潔な表現を使います
• 可能な限り専門用語を避けます
• 実際の例やシナリオを含めます
• 手順に書かれているとおりに実行して検証します

ドキュメントの種類

ユーザーガイド：

• 概要と目標
• 前提条件
• 手順を追った説明
• スクリーンショットまたは例
• トラブルシューティング
• 次のステップ

README ファイル：

• プロジェクト名と説明
• バッジ（ビルド状況、バージョン、ライセンス）
• 機能
• インストール
• クイックスタート
• 使用例
• コントリビューション
• ライセンス

アーキテクチャドキュメント：

• システム概要
• コンポーネント図
• 設計上の決定
• 技術選定
• 統合ポイント
• データフロー

変更履歴の生成

Git コミットの変換

Git コミットからユーザー向けの変更履歴を自動生成します。生成時には、次の処理を行います。

• コミット履歴を分析します
• 変更を分類します（機能、改善、バグ修正、破壊的変更、セキュリティ）
• 技術的なコミットを、明確でユーザーに伝わりやすいリリースノートに変換します
• 内部向けのコミット（リファクタリング、テストなど）を除外します

基本的な使い方

Create a changelog from commits since last release

Generate changelog for all commits from the past week

Create release notes for version 2.5.0

特定の日付範囲を指定する場合

Create a changelog for all commits between March 1 and March 15

カスタムガイドラインを使用する場合

Create a changelog for commits since v2.4.0, using my changelog
guidelines from CHANGELOG_STYLE.md

出力例

# Updates - Week of March 10, 2024

## ✨ New Features

- **Team Workspaces**: Create separate workspaces for different
  projects. Invite team members and keep everything organized.

- **Keyboard Shortcuts**: Press ? to see all available shortcuts.
  Navigate faster without touching your mouse.

## 🔧 Improvements

- **Faster Sync**: Files now sync 2x faster across devices
- **Better Search**: Search now includes file contents, not just titles

## 🐛 Fixes

- Fixed issue where large images wouldn't upload
- Resolved timezone confusion in scheduled posts
- Corrected notification badge count

参考ファイル

詳細なドキュメントのパターンやガイダンスを確認するには、必要に応じて参考ファイルを読み込んでください。

• references/api_docs.md - API ドキュメントのパターン、OpenAPI 仕様、SDK の生成、バージョニング戦略、コード例
• references/technical_writing.md - テクニカルライティングのベストプラクティス、ユーザーガイドの構成、README テンプレート、アーキテクチャドキュメント、コンテンツの構成
• references/changelogs.md - 変更履歴の生成パターン、コミットの分類、ユーザーに伝わりやすい表現への変換、リリースノートのベストプラクティス
• references/API_DOCUMENTATION.template.md - エンドポイント、認証、Webhook、SDK の例を含む REST API ドキュメントのテンプレート
• references/CHANGELOG.template.md - Keep a Changelog 形式と SemVer に準拠した変更履歴のテンプレート
• references/DESIGN_SPEC.template.md - 機能計画、技術設計、実装方針のための設計仕様テンプレート
• references/ARCHITECTURE_DECISION_RECORD.template.md - 背景と結果を含む重要なアーキテクチャ上の決定を記録する ADR テンプレート
• references/MIGRATION_GUIDE.template.md - バージョンアップグレード、破壊的変更、アップグレード手順のための移行ガイドテンプレート

特定の種類のドキュメントを作成する際は、適切な参考ファイルを読み込んでください。

ベストプラクティス

ドキュメントの品質

1. 実例： プレースホルダーではなく、実際に動作する例を使います
2. エラーケース： エラー応答を例とともに記載します
3. 認証： 認証設定の手順を明確に説明します
4. バージョニング： バージョニング戦略と移行手順を記載します
5. テスト： すべての例をテストし、動作することを確認します

開発者エクスペリエンス

• クイックスタート： 5 分で始められるクイックスタートガイドを用意します
• インタラクティブ： Postman や Swagger UI などのツールを使います
• 検索性： ドキュメントを検索できるようにします
• 最新状態の維持： API の変更に合わせてドキュメントを最新の状態に保ちます
• フィードバック： 開発者がフィードバックを送る方法を記載します

執筆ガイドライン

1. 明確さ： シンプルでわかりやすい言葉を使います
2. 構成： 明確な見出しで整理します
3. 例： 実際に動作する例を含めます
4. テスト： すべての手順を自分で試します
5. フィードバック： ユーザーがフィードバックを送る方法を記載します

コンテンツの構成

• 階層： 明確な見出し構造を使います
• ナビゲーション： 長いドキュメントには目次を含めます
• 検索： コンテンツを検索できるようにします
• 相互参照： 関連するセクションにリンクします
• 更新： ドキュメントを最新の状態に保ちます

アクセシビリティ

• 平易な言葉：不要な専門用語は避けます
• 構造：セマンティックな HTML／Markdown を使用します
• 画像：画像には代替テキストを含めます
• 書式：一貫した書式を使用します
• 例：異なるスキルレベルに合わせて複数の例を提示します

変更履歴のベストプラクティス

• git リポジトリのルートから実行します
• 対象を絞った変更履歴を作成する場合は、日付範囲を指定します
• 一貫した書式にするため、CHANGELOG_STYLE.md を使用します
• 公開前に生成された変更履歴を確認し、必要に応じて調整します
• 出力を直接 CHANGELOG.md に保存します

関連するユースケース

• API 仕様の作成
• SDK の生成
• 開発者のオンボーディング
• API 統合ガイド
• バージョン移行ドキュメント
• インタラクティブな API の探索
• ユーザードキュメント
• 開発者向けガイド
• アーキテクチャドキュメント
• チュートリアルの作成
• コンテンツの改善
• GitHub リリースノートの作成
• アプリストアの更新内容の説明文の作成
• ユーザー向けメール更新の生成
• ソーシャルメディア向け告知投稿の作成