technical-writing

Technical Writing

ビルダーや運用担当者向けの内部技術ドキュメントを成果物として作成する場合は、このスキルを使用してください。

technical-writing は、以下を対象とするドキュメント群の中核となるスキルです。

• 技術仕様書
• アーキテクチャドキュメント
• ADR／意思決定記録
• ランブックおよびインシデント対応手順
• ロールアウト／ロールバック／移行ガイド
• 開発者向けの実装・保守ガイド

モードや範囲を選ぶ前に、以下の関連ドキュメントを読んでください。

• references/document-modes-and-boundaries.md
• references/mode-structures.md
• references/quality-checklists.md
• references/docs-as-code-and-maintenance.md

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

• 実装開始前に、チームが技術仕様書を必要としている
• エンジニアが、トレードオフと意思決定を記録したアーキテクチャドキュメントや ADR を必要としている
• 運用担当者が、ランブック、ロールバックガイド、インシデント対応手順を必要としている
• 移行やロールアウトに、検証とロールバックに関する記述を含む、長期的に参照できる手順書が必要である
• 開発者向けの内部ガイドで、システムの仕組みや、安全に作業する方法を説明する必要がある

このスキルを使用しない場合

• 公開 API ドキュメント、SDK ドキュメント、OpenAPI リファレンス、開発者ポータルのコンテンツ → api-documentation
• リリースノート、CHANGELOG.md、顧客や開発者向けの移行告知 → changelog-maintenance
• スライド、ピッチデッキ、ロードマップのプレゼンテーション、アーキテクチャのデモ → presentation-builder
• 製品のポジショニング、ローンチ用コピー、GTM メッセージング、マーケティングの自動化 → marketing-automation
• ドキュメントを書く前に、機能や API 自体を決めることが主な目的である → まず task-planning、api-design、または該当する計画スキルを使用します

手順

Step 1: 主となるモードを 1 つ分類する

下書きを始める前に、依頼を主となるモード 1 つに整理します。

technical_writing_mode:
  primary_mode: spec | architecture | adr | runbook | migration | internal-guide
  audience: engineers | operators | mixed | unknown
  source_of_truth: repo | incident-notes | existing-doc | mixed | unknown
  lifecycle_state: draft | review | rewrite | maintenance
  docs_surface: markdown-repo | docs-site | wiki | unknown
  review_need: decision-signoff | operational-accuracy | handoff-clarity | unknown

1 回の実行につき、主となるモードを 1 つ使用します。

• spec → 計画中の変更、目標、制約、設計、ロールアウト、ロールバック、未解決の質問
• architecture → システム構造、境界、インターフェース、トレードオフ、障害モード
• adr → 1 つの重要な意思決定、その選択肢と根拠
• runbook → 運用、診断、復旧、エスカレーション
• migration → 検証とロールバックを含む、安全な旧方式から新方式への移行
• internal-guide → 保守担当者向けの実装に関する説明

Step 2: 読者と他のスキルへの振り分けを確認する

執筆前に、次の 3 つの質問に答えます。

1. このドキュメントを読んで作業するのは誰ですか？
2. このドキュメントによって、どのような意思決定や行動を可能にしますか？
3. 対象範囲から外すべき隣接スキルはどれですか？

振り分けの早見表：

依頼の内容	使用するスキル
API、SDK、Webhook、開発者ポータル向けのドキュメントを公開する	api-documentation
チュートリアル、オンボーディングガイド、FAQ を作成する	ここで対応します。エンドユーザー向けガイドモードを使用してください
リリース済みの変更を要約する、または CHANGELOG.md を保守する	changelog-maintenance
ローンチ、ロードマップ、アーキテクチャレビュー用のスライドを作成する	presentation-builder
ローンチや製品のメッセージを作成する	marketing-automation
ドキュメントを書く前に API や機能の設計を決定する	api-design、task-planning、または別の計画スキル

Step 3: 必要最低限の技術的根拠を集める

根拠のない感覚だけで下書きを作成しないでください。まず、信頼できる根拠を必要最低限集めます。

• 現在の動作やアーキテクチャに関する記録
• インターフェース、スキーマ、コマンド、運用上のシグナル
• ロールアウトや運用上の制約
• 既知の障害モードと復旧手順
• 未解決の質問やトレードオフ

根拠が不足している場合は、ドキュメントが正式な情報源であるかのように装わず、前提を明示してください。

Step 4: 要件に合う最小限の構成を選ぶ

references/mode-structures.md を参照し、選択したモードに合うセクションだけを残してください。

ステップ 5：モード固有の執筆ルールを適用する

• 仕様書では、目標と対象外を分けて記述します。
• アーキテクチャ文書では、すべてのコードパスではなく、境界とトレードオフを説明します。
• ADRでは、1つの決定を記録し、設計文書全体にしないようにします。
• ランブックでは、緊急時にすばやく行動できることを優先します。
• 移行ガイドでは、互換性、検証、ロールバックを前面に出します。
• 社内ガイドでは、顧客向けの教育やマーケティング上の価値提案ではなく、実装の実態を説明します。

ステップ 6：ドキュメントをコードとして扱いやすくする

レビューしやすく、リポジトリになじむ記述を基本とします。

• 安定した見出し
• 運用担当者がざっと確認しやすい簡潔な箇条書き
• 明示的なコマンド、パス、担当者、前提条件
• ADR形式の文書では、決定日とステータスを記載
• 可能な場合は、説明の重複を避け、信頼できる情報源となる文書へのリンクを記載

ステップ 7：品質チェックを行う

仕上げる前に、次の点を確認します。

1. 対象読者が明記されているか、明確にわかる。
2. 文書によって可能になる決定やアクションが記載されている。
3. 前提条件と不明点にラベルが付いている。
4. 該当する場合、コマンド、インターフェース、検証、ロールバック、エスカレーションが具体的である。
5. 隣接するドキュメント作成スキルの範囲まで取り込んでいない。
6. タイトルとセクション構成が選択したモードに合っている。

ステップ 8：概要または完成した成果物を返す

本文をすべて作成する前に提示する概要の推奨形式：

# Technical Writing Brief

## Mode
- Primary mode:
- Why it fits:
- Audience:

## Source material used
- Repo/docs/evidence:
- Assumptions / gaps:

## Draft structure
1. section
2. section
3. section

## Writing notes
- Key decisions / actions enabled:
- Risks / unknowns:
- Route-outs kept out of scope:

ユーザーがすでに完成した成果物を求めている場合は、上記の構成に合った選択済みの文書をそのまま作成します。

例

例 1：実装前の社内設計文書

入力

ワーカキューを Redis のリストから Redis Streams に移行するための技術仕様書を作成してください。エンジニアがコーディングを始める前に、目標、制約、ロールアウト、ロールバックを把握できるようにしてください。

望ましい出力の方向性

• モード：spec
• 対象読者：エンジニア
• 目標、対象外、制約、設計、ロールアウト、ロールバック、未解決の質問を含める
• API ポータルへの公開は対象外とする

例 2：アーキテクチャ上の決定の記録

入力

デュアルライトではなく Postgres の論理レプリケーションを採用しました。決定と代替案を ADR に記録してください。

望ましい出力の方向性

• 背景、決定、代替案、結果、フォローアップを記録する
• 文書を短く、決定に焦点を当てたものにする

例 3：インシデント対応ランブック

入力

payments ワーカーのバックログが急増し、リトライがタイムアウトし始めた場合のランブックを作成してください。

望ましい出力の方向性

• モード：runbook
• 症状、初動確認、運用手順、エスカレーション、ロールバック／復旧を含める
• 文章としての説明より、オペレーターが迅速に行動できることを優先する

例 4：API ドキュメントとの境界

入力

外部開発者向けの公開 webhook クイックスタートと認証トラブルシューティングページを更新してください。

望ましい出力の方向性

• api-documentation に振り分ける
• 主な目的は、社内向け技術文書ではなく、公開する開発者向け API ドキュメントであると説明する

ベストプラクティス

1. 本文を書く前に、文書のモードを選びます。
2. 社内向け技術文書は、決定とアクションを中心に記述します。
3. モードに必要なセクションだけを書き、すべてのテンプレートをあらゆる文書に無理に適用しないようにします。
4. 社内向けの設計・運用文書は、API ポータル、ユーザーヘルプ、リリースノート、プレゼン資料、GTM 向けの文面と分けます。
5. レビューしやすい Markdown、安定した見出し、情報源へのリンクを備えた事実を用い、ドキュメントをコードとして扱いやすい構成にします。
6. 前提条件と未解決の質問には、明確にラベルを付けます。
7. ランブックと移行ガイドでは、ロールバックとエスカレーションを見つけやすくします。
8. リクエストによって対象読者が変わる場合は、社内文書の範囲を無理に広げず、適切な分野に振り分けます。

参考資料

• Diátaxis
• Write the Docs — Docs as Code
• Write the Docs — How to write software documentation
• Architectural Decision Records
• Keep a Changelog