Technical Writer について
開発者、DevOps エンジニア、プロダクトマネージャー、技術チーム向けのテクニカルライティングスキルです。API 文書、ユーザーガイド、README、アーキテクチャ文書の作成を支援します。
主な機能
- 01API リファレンス文書の作成
- 02ユーザーガイドとチュートリアルの作成
- 03README の構成
- 04アーキテクチャとデータフローの記録
- 05トラブルシューティングと移行ガイドの作成
活用シーン
- 01ソフトウェア API の文書化
- 02製品機能のユーザーガイド作成
- 03システム設計の記録と README の改善
インストール
コマンドをコピーしてターミナルで実行します。
$
npx skills add https:/インストール後、Claude Code で/technical-writerを入力して読み込まれたか確認します。
詳細
テクニカルライター
複雑な技術概念を、ユーザーの成功を支援する、明快でわかりやすいドキュメントに変換します。このスキルは、技術的な正確さと読みやすさのバランスを取りながら、API ドキュメント、ユーザーガイド、README ファイル、チュートリアル、リファレンス資料を作成することに特化しています。
コードライブラリ、ソフトウェア製品、システムアーキテクチャ、プロセスのいずれを文書化する場合も、このスキルを使えば、包括的で整理され、実際に役立つドキュメントを作成できます。構成、書式、コンテンツ整理に関する業界のベストプラクティスに従います。
技術者にも技術者以外にも理解しやすく、効果的に利用できるドキュメントを作成する必要がある、ソフトウェア開発者、DevOps エンジニア、プロダクトマネージャー、技術チームに最適です。
主なワークフロー
ワークフロー 1：API ドキュメント
- コードベースの分析 - API エンドポイント、パラメーター、レスポンスを確認します
- リファレンスの構成 - リソース／エンドポイントごとに、一貫した書式で整理します
- エンドポイントの文書化 - 明確な説明、パラメーター、リクエスト／レスポンスの例を記載します
- コードサンプルの追加 - 複数の言語で例を掲載します
- クイックスタートの作成 - 認証を含む入門ガイドを作成します
- エラーリファレンスの作成 - エラーコードとトラブルシューティングを文書化します
- OpenAPI 仕様の生成 - 機械可読な API 仕様を作成します
ワークフロー 2：ユーザーガイドの作成
- 対象読者の分析 - ユーザーのペルソナとスキルレベルを特定します
- タスクの洗い出し - すべてのユーザータスクとワークフローを一覧にします
- コンテンツの概要作成 - 機能ではなく、ユーザーの利用の流れに沿ってガイドを構成します
- 手順の作成 - スクリーンショットを含む、ステップごとの説明を作成します
- 背景情報の追加 - 方法だけでなく、理由とタイミングも説明します
- ナビゲーションの構築 - わかりやすい目次、索引、検索キーワードを作成します
- ドキュメントのテスト - 実際のユーザーシナリオに照らして検証します
ワークフロー 3：優れた README の作成
- プロジェクトの概要 - 何をするプロジェクトなのかを1段落で説明します
- インストール - 前提条件を含む、明確なセットアップ手順を記載します
- クイックスタート - すぐに実行できる最小限の例を用意します
- 使用例 - 実用的なコードサンプルと説明を記載します
- 設定 - すべてのオプション、環境変数、フラグを文書化します
- コントリビューション - 貢献方法のガイドラインと開発環境のセットアップを記載します
- ライセンスとクレジット - 法的情報と謝辞を記載します
ワークフロー 4：アーキテクチャのドキュメント化
- システム概要 - 高レベルの図と説明を用意します
- コンポーネントの詳細 - 主要な各コンポーネントとその役割を詳しく説明します
- データフロー - システム内で情報がどのように流れるかを文書化します
- デプロイ - インフラストラクチャ、スケーリング、監視に関する考慮事項を記載します
- セキュリティモデル - 認証、認可、データ保護について説明します
- 意思決定記録 - アーキテクチャ上の決定とその根拠を文書化します
クイックリファレンス
| 操作 | コマンド／トリガー |
|---|---|
| API ドキュメントの作成 | "この API を文書化して" |
| README の作成 | "このプロジェクトの README を作成して" |
| ユーザーガイド | "[feature] のユーザーガイドを書いて" |
| トラブルシューティングのセクション | "トラブルシューティングガイドを作成して" |
| チュートリアル | "[task] のチュートリアルを書いて" |
| リリースノート | "変更内容からリリースノートを生成して" |
| 移行ガイド | "[version] への移行ガイドを書いて" |
| コードコメント | "このコードを文書化して" |
ベストプラクティス
- まず目的を説明する - 詳細に入る前に、目的とユースケースを説明します
- 動作する例を示す - すべての概念に具体的なコード例を用意します
- 一貫性を保つ - 用語、書式、構成を全体で統一します
- 流し読みしやすくする - 見出し、リスト、表、コードブロックを積極的に使います
- すべてをテストする - すべてのコード例が実際に動作することを確認します
- バージョンを明記する - 各機能や動作がどのバージョンに適用されるかを示します
- 先回りして更新する - コードの変更に合わせてドキュメントを更新します
- 関連リンクを適切に設ける - 読者を圧倒しない範囲で、関連する概念をつなぎます
- 図を使う - 複雑なフローは視覚的に表現します
- 検索しやすさを保つ - Ctrl+F やサイト内検索で見つけやすくします
- 背景を説明する - 使い方だけでなく、いつ、なぜ使うのかも説明します
- エラーに適切に対処する - よくあるエラーと解決方法を記載します
- 国際化を意識して書く - 翻訳しやすい、明快で簡潔な言葉を使います
- 前提条件を記載する - 事前知識があると決めつけないようにします
- すぐに成果を得られる方法を紹介する - 5分以内に成功体験を得られるようにします
コメント
Markdown 対応