technical-writer

Technical Writer

読者中心のアプローチで、明確で実用的な技術ドキュメントを作成するスキル。

適用場面

• プロジェクトの README や Getting Started ガイドを作成する場合
• API の認証・利用手順・コード例をまとめたデベロッパーガイドを作成する場合
• インストール手順・セットアップガイドを整備する場合
• ステップバイステップのチュートリアルを作成する場合
• アーキテクチャ設計・技術仕様を記述する場合
• トラブルシューティングガイドを作成する場合

5つのコア原則

1. 読者中心（User-Centered）

「どう動くか」よりも先に「なぜ使うべきか」に答える。

❌ このツールは --recursive フラグを受け付けます。
✅ 大量のファイルを一括処理する場合は --recursive フラグを使用します。

2. 明瞭さ優先（Clarity First）

• 1文は25語（日本語で50〜60字）以内
• 1段落に1つのアイデア
• 能動態を使う（受動態は最小限に）
• 専門用語を使う場合は初出時に説明する

3. 具体的なコード例（Show, Don't Tell）

動作確認済みのコードと期待される出力を必ず示す。

# ファイルを再帰的に並べ替える
filesort . --recursive --output sorted/

# 出力例:
# ✓ 42 files processed
# ✓ Sorted into 8 directories

4. 段階的な開示（Progressive Disclosure）

• クイックスタートを最初に置く（5分で動かせる手順）
• 基本 → 応用 → エッジケースの順に構成する
• 詳細設定は別セクションに分離する

5. スキャンしやすい構造（Scannable Content）

• 説明的な見出しを使う（「設定」より「データベース接続を設定する」）
• コードブロック、箇条書き、テーブルを活用する
• 重要な UI 要素は 太字 で強調する
• コマンド・変数・ファイルパスは コードフォーマット を使う

---

ワークフロー

各ステップを順に実行する。

ステップ0: スコーピング（実行前確認）

以下を確認し、該当しない場合は中断して適切なスキルを提案する:

• ドキュメントの種類が明確であること — README なのか、ガイドなのか、API ドキュメントなのかを特定する。SKILL.md の作成は skill-creator へ委譲する
• 対象の成果物・コードが存在すること — まだ実装されていないものについてドキュメントを書く場合は、先に実装を促す
• 既存ドキュメントの有無を確認すること — 既にドキュメントが存在する場合は「新規作成」ではなく「更新」モードで実行する

ステップ1: 対象読者とゴールを明確化する

執筆前に確認する:

• 読者は誰か（初心者 / 中級者 / 上級者）？
• 読者はこのドキュメントを読んで何ができるようになるべきか？
• 前提知識は何か（OS、プログラミング言語、フレームワーク等）？
• ドキュメントのスコープはどこまでか？

不明な点はユーザーに確認してから進む。

ステップ2: ドキュメントの種類を選択する

下記「テンプレート」から最適な形式を選ぶ。複数の形式が必要な場合は分割して作成する。

ステップ3: テンプレートをベースに執筆する

テンプレートに沿いながら以下を意識する:

• 冒頭で「これは何か・なぜ使うか」を1段落で説明する
• コード例には必ずコメントと期待される出力を付ける
• 環境別（Windows / macOS / Linux）の差異がある場合は全て記載する
• プレースホルダーには YOUR_VALUE 形式の大文字を使う

ステップ4: セルフレビューをする

執筆後に確認する:

• クイックスタートで5分以内に動作確認できるか
• すべてのコード例が実行可能か
• Windows と Unix の両方のコマンドが記載されているか（対象の場合）
• 見出しは動詞から始まる説明的な文になっているか
• プレースホルダーはすべて YOUR_VALUE 形式か

---

テンプレート集

テンプレート1: プロジェクト README

# プロジェクト名

[1〜2文でプロジェクトの説明と価値を述べる]

## 特徴

- 特徴1（ユーザーにとってのメリットを述べる）
- 特徴2
- 特徴3

## クイックスタート

### 前提条件

- Node.js 18 以上
- Git

### インストール

**Windows (PowerShell)**
\`\`\`powershell
git clone https://github.com/YOUR_ORG/YOUR_REPO.git
cd YOUR_REPO
npm install
\`\`\`

**macOS / Linux**
\`\`\`bash
git clone https://github.com/YOUR_ORG/YOUR_REPO.git
cd YOUR_REPO
npm install
\`\`\`

### 起動

\`\`\`bash
npm start
# → http://localhost:3000 で起動します
\`\`\`

## 使い方

[基本的な使い方のコード例と出力を記載]

## 設定

| 環境変数 | 説明 | デフォルト値 |
|---|---|---|
| `PORT` | サーバーポート番号 | `3000` |
| `DATABASE_URL` | データベース接続文字列 | — |

## トラブルシューティング

**`Error: Cannot find module` が表示される場合**
```bash
npm install  # 依存関係を再インストール

ライセンス

[LICENSE_TYPE] — 詳細は LICENSE を参照。

---

### テンプレート2: デベロッパーガイド

OpenAPI サンプル: [references/openapi.yaml](references/openapi.yaml)

```markdown
# [API_NAME] デベロッパーガイド

[この API が何を解決するか・どんな開発者向けかを2〜3文で説明する]

## 前提条件

- アカウント登録と API キーの取得 → [ダッシュボードへのリンク]
- 対応言語・ランタイムバージョン（例: Python 3.9+, Node.js 18+）
- 認証方式の理解（Bearer トークン / API キー / OAuth 2.0 等）

## クイックスタート（5分）

### 1. 認証を設定する

**Windows (PowerShell)**
\`\`\`powershell
$env:YOUR_API_KEY = "YOUR_API_KEY_HERE"
\`\`\`

**macOS / Linux**
\`\`\`bash
export YOUR_API_KEY="YOUR_API_KEY_HERE"
\`\`\`

### 2. 最初のリクエストを送る

\`\`\`python
import httpx

client = httpx.Client(headers={"Authorization": f"Bearer {YOUR_API_KEY}"})
response = client.get("https://api.example.com/v1/resources")
print(response.json())
# → {"items": [...], "total": 42}
\`\`\`

\`\`\`typescript
const response = await fetch("https://api.example.com/v1/resources", {
  headers: { Authorization: `Bearer ${process.env.YOUR_API_KEY}` },
});
const data = await response.json();
\`\`\`

✓ `200 OK` が返れば接続成功です。

## 主要ユースケース

### ユースケース1: [USECASE_TITLE]

[何を達成するかを1文で説明]

\`\`\`python
# [操作の説明]
result = client.post("/v1/resources", json={"name": "my-item"})
print(result.json())  # → {"id": "res_abc123", "name": "my-item"}
\`\`\`

### ユースケース2: [USECASE_TITLE]

...

## エラーハンドリング

| ステータス | 意味 | 対処方法 |
|---|---|---|
| `400` | リクエスト不正 | レスポンスの `message` フィールドを確認する |
| `401` | 認証失敗 | API キーを再確認する |
| `429` | レート制限超過 | `Retry-After` ヘッダーの秒数だけ待機して再試行する |
| `5xx` | サーバーエラー | 指数バックオフで最大3回リトライする |

\`\`\`python
try:
    response = client.post("/v1/resources", json=payload)
    response.raise_for_status()
except httpx.HTTPStatusError as e:
    if e.response.status_code == 429:
        time.sleep(int(e.response.headers.get("Retry-After", 60)))
\`\`\`

## レート制限と制約

| 項目 | 制限値 |
|---|---|
| リクエスト数 | 1,000 req/分 |
| ペイロードサイズ | 最大 10 MB |
| 同時接続数 | 最大 20 |

## SDK とライブラリ

| 言語 | パッケージ | インストール |
|---|---|---|
| Python | `YOUR_SDK_PYTHON` | `pip install YOUR_SDK_PYTHON` |
| TypeScript | `YOUR_SDK_TS` | `npm install YOUR_SDK_TS` |

## OpenAPI 仕様書

エンドポイントの完全な仕様は [openapi.yaml](./openapi.yaml) を参照してください。

## サポート・フィードバック

- 公式ドキュメント: [URL]
- 変更履歴: [CHANGELOG へのリンク]
- Issue 報告: [GitHub Issues / サポートフォーム]

---

テンプレート3: ステップバイステップ チュートリアル

# チュートリアル: [TASK_NAME]

このチュートリアルでは [GOAL] の方法を説明します。

## 所要時間

約 [N] 分

## 前提条件

- [ ] [ツール名] がインストール済み → [インストールガイドへのリンク]
- [ ] [サービス名] のアカウントを持っている

## ステップ1: [STEP_TITLE]

[このステップで何をするか・なぜするかを1文で説明]

**Windows (PowerShell)**
\`\`\`powershell
New-Item -ItemType Directory -Path "my-project"
Set-Location my-project
\`\`\`

**macOS / Linux**
\`\`\`bash
mkdir my-project && cd my-project
\`\`\`

✓ この時点で `my-project/` ディレクトリが作成されています。

## ステップ2: [STEP_TITLE]

...（各ステップに確認チェックポイントを入れる）

## 完了

[達成したことを1〜2文でまとめる]

次のステップ:
- [発展的なトピック1](link)
- [発展的なトピック2](link)

---

スタイルガイド

言語と口調

項目	推奨	非推奨
人称	「あなた」「ユーザー」	「自分」「君」
文体	ですます調（丁寧体）	だ・である調
命令形	「〜してください」「〜します」	「〜せよ」
専門用語	初出時に括弧で英語を補記	説明なしの略語

フォーマット規則

要素	形式	例
UI ボタン・メニュー	太字	「送信」ボタンをクリック
コマンド・コード	バッククオート	npm install
ファイル・パス	バッククオート	src/index.ts
プレースホルダー	大文字スネークケース	YOUR_API_KEY
強調・注意	> ブロッククオート	> 注意: ...

Windows 固有の考慮事項

• パス区切り文字: \（ドキュメントには / も併記するか、クロスプラットフォームツールを推奨）
• 環境変数: $env:VARIABLE_NAME（PowerShell）/ %VARIABLE_NAME%（cmd）
• シェルスクリプト: .sh の代替として .ps1 の例を記載する
• 改行コード: Git の autocrlf 設定に注意が必要な場合は明記する

GitHub Copilot / Claude Code との連携

ドキュメントを生成・改善する際は、以下のプロンプトパターンが有効:

「[ファイルパス] を読んで、technical-writer スキルに従い README を作成して」
「この API のデベロッパーガイドを日本語で作成して。openapi.yaml も参照して」
「このチュートリアルをレビューして、5つのコア原則に沿って改善点を提案して」