Technical Writer

テクニカルライター

優れたドキュメントがあれば、使い続けてもらえる製品と、使われなくなる製品の違いが生まれます。

基本原則

自分ではなく、読者に向けて書きましょう。

優れたドキュメントは次のことを実現します。

• 質問される前に疑問に答える
• ユーザーがすばやく成果を得られるようにする
• サポートの負担を軽減する
• チーム間でナレッジを共有する

---

ドキュメントの種類

1. API ドキュメント

対象読者： API を統合する開発者
目標： サポートを受けずに統合できるようにする

2. ユーザーガイド

対象読者： エンドユーザー
目標： ユーザーがタスクを完了できるよう支援する

3. チュートリアル

対象読者： 学習者
目標： 実践を通して概念を教える

4. リファレンスドキュメント

対象読者： 詳細情報を必要とする開発者
目標： パラメーターやメソッドをすばやく調べられるようにする

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

対象読者： システムを保守するエンジニア
目標： システム設計の判断を理解できるようにする

---

フェーズ 1：API ドキュメント

OpenAPI / Swagger 仕様

# openapi.yaml
openapi: 3.0.0
info:
  title: User API
  version: 1.0.0
  description: API for managing users

servers:
  - url: https://api.example.com/v1
    description: Production server

paths:
  /users:
    get:
      summary: List all users
      description: Returns a paginated list of users
      parameters:
        - name: page
          in: query
          description: Page number
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          description: Items per page
          schema:
            type: integer
            default: 20
            maximum: 100
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      summary: Create a user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - name
              properties:
                email:
                  type: string
                  format: email
                  example: [email protected]
                name:
                  type: string
                  example: John Doe
      responses:
        '201':
          description: User created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          $ref: '#/components/responses/BadRequest'

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email
        name:
          type: string
        createdAt:
          type: string
          format: date-time

    Pagination:
      type: object
      properties:
        page:
          type: integer
        limit:
          type: integer
        total:
          type: integer

  responses:
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: Unauthorized

    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
              details:
                type: array
                items:
                  type: string

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

security:
  - bearerAuth: []

API ドキュメントの構成

# User API

## Authentication

All API requests require authentication using a Bearer token:

Authorization: Bearer YOUR_API_KEY

Get your API key from the [dashboard](https://dashboard.example.com).

## Base URL

https://api.example.com/v1

## Rate Limiting

- 100 requests per minute per API key
- 1000 requests per hour per API key

Rate limit headers:

X-RateLimit-Limit: 100 X-RateLimit-Remaining: 99 X-RateLimit-Reset: 1640000000

## Errors

Standard HTTP status codes:

| Code | Meaning |
|------|---------|
| 200 | Success |
| 201 | Created |
| 400 | Bad Request - Invalid parameters |
| 401 | Unauthorized - Missing or invalid API key |
| 403 | Forbidden - Insufficient permissions |
| 404 | Not Found |
| 429 | Too Many Requests - Rate limit exceeded |
| 500 | Internal Server Error |

Error response format:
```json
{
  "error": "Invalid email format",
  "code": "VALIDATION_ERROR",
  "details": {
    "field": "email",
    "message": "Must be a valid email address"
  }
}

エンドポイント

ユーザー一覧の取得

GET /users

ページ分割されたユーザー一覧を返します。

クエリパラメーター：

パラメーター	型	デフォルト	説明
page	integer	1	ページ番号
limit	integer	20	1 ページあたりの項目数（最大 100）
sort	string	created_at	並べ替えフィールド
order	string	desc	並べ替え順（asc/desc）

リクエスト例：

curl -X GET "https://api.example.com/v1/users?page=1&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

レスポンス例：

{
  "data": [
    {
      "id": "usr_123",
      "email": "[email protected]",
      "name": "John Doe",
      "createdAt": "2024-01-22T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "pages": 5
  }
}

ユーザーの作成

POST /users

新しいユーザーを作成します。

リクエストボディ：

{
  "email": "[email protected]",
  "name": "John Doe",
  "role": "user"
}

パラメーター：

フィールド	型	必須	説明
email	string	はい	ユーザーのメールアドレス
name	string	はい	ユーザーの氏名
role	string	いいえ	ユーザーのロール（デフォルト：user）

リクエスト例：

curl -X POST "https://api.example.com/v1/users" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "name": "John Doe"
  }'

レスポンス例：

{
  "id": "usr_123",
  "email": "[email protected]",
  "name": "John Doe",
  "role": "user",
  "createdAt": "2024-01-22T10:30:00Z"
}

SDK

JavaScript / TypeScript

npm install @example/api-client

import { ExampleAPI } from '@example/api-client'

const client = new ExampleAPI('YOUR_API_KEY')

// List users
const users = await client.users.list({ page: 1, limit: 20 })

// Create user
const user = await client.users.create({
  email: '[email protected]',
  name: 'John Doe'
})

Python

pip install example-api

from example_api import Client

client = Client('YOUR_API_KEY')

# List users
users = client.users.list(page=1, limit=20)

# Create user
user = client.users.create(
    email='[email protected]',
    name='John Doe'
)

Webhook

Webhook を使ってイベントを購読します。

{
  "url": "https://yourdomain.com/webhook",
  "events": ["user.created", "user.updated", "user.deleted"]
}

Webhook のペイロード：

{
  "event": "user.created",
  "timestamp": "2024-01-22T10:30:00Z",
  "data": {
    "id": "usr_123",
    "email": "[email protected]"
  }
}

変更履歴

v1.1.0 (2024-01-22)

• 一覧エンドポイントに sort と order パラメーターを追加
• エラーメッセージを改善

v1.0.0 (2024-01-01)

• 初回リリース

---

## Phase 2: User Guides

### Structure

```markdown
# Getting Started Guide

## What You'll Learn

In this guide, you'll learn how to:
- Set up your account
- Create your first project
- Invite team members
- Deploy to production

**Time required:** 15 minutes

## Prerequisites

Before you begin, make sure you have:
- [ ] An account (sign up at example.com)
- [ ] Node.js 18+ installed
- [ ] Basic command line knowledge

## Step 1: Create a Project

1. Log in to your [dashboard](https://dashboard.example.com)
2. Click **New Project**
3. Enter your project name
4. Select a region (choose the one closest to your users)
5. Click **Create**

![Create Project Screenshot](./images/create-project.png)

**Tip:** You can create up to 5 projects on the free plan.

## Step 2: Install the CLI

Open your terminal and run:

```bash
npm install -g @example/cli

インストールを確認します。

example --version

次のように表示されます：example CLI v1.0.0

ステップ 3：認証する

アカウントにログインします。

example login

ブラウザーが開きます。Authorize をクリックして続行してください。

ステップ 4：アプリをデプロイする

アプリのディレクトリに移動します。

cd my-app

デプロイします。

example deploy

アプリは https://your-app.example.com で公開されます。

次のステップ

• カスタムドメインを設定する
• 環境変数を設定する
• チームメンバーを追加する

トラブルシューティング

"Command not found: example"

解決策： npm のグローバル bin ディレクトリが PATH に含まれていることを確認してください。

次を実行します。

npm config get prefix

/bin を PATH に追加してください。

"Authentication failed"

解決策：

1. ログアウトします：example logout
2. 再度ログインします：example login
3. 正しいアカウントを使用していることを確認してください

ヘルプが必要ですか？

• ドキュメント
• コミュニティフォーラム
• サポート

---

## Phase 3: Tutorials

### Tutorial Structure

```markdown
# Build a Todo App with Example Framework

## What You'll Build

In this tutorial, you'll build a fully functional todo app with:
- ✅ Add, edit, and delete todos
- ✅ Mark todos as complete
- ✅ Filter by status
- ✅ Persist data to database

**Final result:** [Live Demo](https://todo-demo.example.com)

## Prerequisites

- Node.js 18+
- Basic JavaScript knowledge
- 30 minutes

## Step 1: Set Up Project

Create a new project:

```bash
npx create-example-app my-todo-app
cd my-todo-app
npm install

開発サーバーを起動します。

npm run dev

http://localhost:3000 を開きます。ウェルカムページが表示されます。

ステップ 2：Todo コンポーネントを作成する

components/Todo.jsx を作成します。

export function Todo({ todo, onToggle, onDelete }) {
  return (
    <div className="todo">
      <input type="checkbox" checked={todo.completed} onChange={() => onToggle(todo.id)} />
      <span className={todo.completed ? 'completed' : ''}>{todo.text}</span>
      <button onClick={() => onDelete(todo.id)}>Delete</button>
    </div>
  )
}

ここで行われていること：

• onToggle は Todo の完了／未完了を切り替えます
• onDelete は Todo を削除します
• CSS クラス completed は完了した Todo のスタイルを設定します

ステップ 3：TodoList コンポーネントを作成する

components/TodoList.jsx を作成します：

import { useState } from 'react'
import { Todo } from './Todo'

export function TodoList() {
  const [todos, setTodos] = useState([])
  const [newTodo, setNewTodo] = useState('')

  const addTodo = () => {
    if (!newTodo.trim()) return

    setTodos([
      ...todos,
      {
        id: Date.now(),
        text: newTodo,
        completed: false
      }
    ])

    setNewTodo('')
  }

  const toggleTodo = id => {
    setTodos(todos.map(todo => (todo.id === id ? { ...todo, completed: !todo.completed } : todo)))
  }

  const deleteTodo = id => {
    setTodos(todos.filter(todo => todo.id !== id))
  }

  return (
    <div>
      <h1>My Todos</h1>

      <div className="add-todo">
        <input
          value={newTodo}
          onChange={e => setNewTodo(e.target.value)}
          placeholder="What needs to be done?"
          onKeyPress={e => e.key === 'Enter' && addTodo()}
        />
        <button onClick={addTodo}>Add</button>
      </div>

      <div className="todo-list">
        {todos.map(todo => (
          <Todo key={todo.id} todo={todo} onToggle={toggleTodo} onDelete={deleteTodo} />
        ))}
      </div>
    </div>
  )
}

主な概念：

• useState で todo のリストを管理します
• map で各 todo をレンダリングします
• filter で削除された todo を取り除きます

ステップ 4：フィルタリングを追加する

TodoList.jsx を更新します：

const [filter, setFilter] = useState('all') // 'all', 'active', 'completed'

const filteredTodos = todos.filter(todo => {
  if (filter === 'active') return !todo.completed
  if (filter === 'completed') return todo.completed
  return true
})

// In JSX:
<div className="filters">
  <button onClick={() => setFilter('all')}>All</button>
  <button onClick={() => setFilter('active')}>Active</button>
  <button onClick={() => setFilter('completed')}>Completed</button>
</div>

<div className="todo-list">
  {filteredTodos.map(todo => (
    <Todo key={todo.id} todo={todo} onToggle={toggleTodo} onDelete={deleteTodo} />
  ))}
</div>

ステップ 5：データベースに永続化する

Prisma をインストールします：

npm install @prisma/client
npm install -D prisma
npx prisma init

prisma/schema.prisma でスキーマを定義します：

model Todo {
  id        String   @id @default(uuid())
  text      String
  completed Boolean  @default(false)
  createdAt DateTime @default(now())
}

マイグレーションを実行します：

npx prisma migrate dev --name init

API ルート app/api/todos/route.ts を作成します：

import { prisma } from '@/lib/db'

export async function GET() {
  const todos = await prisma.todo.findMany()
  return Response.json(todos)
}

export async function POST(request: Request) {
  const { text } = await request.json()

  const todo = await prisma.todo.create({
    data: { text }
  })

  return Response.json(todo)
}

API を使うように TodoList.jsx を更新します：

useEffect(() => {
  fetch('/api/todos')
    .then(res => res.json())
    .then(data => setTodos(data))
}, [])

const addTodo = async () => {
  if (!newTodo.trim()) return

  const response = await fetch('/api/todos', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ text: newTodo })
  })

  const todo = await response.json()
  setTodos([...todos, todo])
  setNewTodo('')
}

学んだこと

• ✅ コンポーネントの構成
• ✅ useState による状態管理
• ✅ イベント処理
• ✅ 条件付きレンダリング
• ✅ API 連携
• ✅ データベースへの永続化

次のステップ

• todo に期限を追加する
• ドラッグ＆ドロップによる並べ替えを実装する
• ユーザー認証を追加する
• 本番環境にデプロイする

コード全文

GitHub で見る

---

## Phase 4: Reference Documentation

### Component Documentation

```markdown
# Button Component

## Import

```typescript
import { Button } from '@/components/Button'

使用方法

<Button variant="primary" size="md" onClick={handleClick}>
  Click me
</Button>

Props

Prop	型	デフォルト	説明
children	ReactNode	必須	ボタンのコンテンツ
variant	'primary' | 'secondary' | 'danger'	'primary'	見た目のスタイル
size	'sm' | 'md' | 'lg'	'md'	ボタンのサイズ
onClick	() => void	-	クリック時のハンドラー
disabled	boolean	false	無効状態
loading	boolean	false	読み込みスピナーを表示
type	'button' | 'submit' | 'reset'	'button'	HTML ボタンの種類
fullWidth	boolean	false	ボタンを全幅にする

例

プライマリボタン

<Button variant="primary">Save</Button>

セカンダリボタン

<Button variant="secondary">Cancel</Button>

危険ボタン

<Button variant="danger" onClick={handleDelete}>
  Delete
</Button>

読み込み状態

<Button loading disabled>
  Processing...
</Button>

全幅

<Button fullWidth>Submit</Button>

アクセシビリティ

• セマンティックな <button> 要素を使用します
• キーボード操作（Enter、Space）に対応しています
• 読み込み中は適切な ARIA 属性を含めます
• WCAG AA のコントラスト要件を満たしています

関連コンポーネント

• IconButton
• LinkButton

---

## Documentation Tools

### Docusaurus (Recommended)

```bash
npx create-docusaurus@latest my-docs classic

cd my-docs
npm start

構成：

my-docs/
├── docs/              # Documentation markdown files
│   ├── intro.md
│   ├── api/
│   └── guides/
├── blog/              # Blog posts
├── src/
│   └── pages/         # Custom React pages
├── static/            # Images, assets
├── docusaurus.config.js
└── sidebars.js        # Sidebar navigation

その他のツール

• GitBook - 美しく、使いやすい
• MkDocs - Python 製でシンプル
• Mintlify - AI を活用したモダンなツール
• ReadMe.io - API に特化
• Notion - 社内ドキュメント向け

---

ドキュメント作成のベストプラクティス

✅ 推奨事項

能動態を使う：

✅ "Click the button to save"
❌ "The button should be clicked to save"

簡潔にする：

✅ "Returns user data"
❌ "This endpoint will return the data associated with the user"

例を使う：

✅ "Set `timeout` to 5000 (5 seconds)"
❌ "Set the timeout parameter"

長い内容を分割する：

✅ Use headings, lists, code blocks
❌ Long paragraphs of text

エラー処理を含める：

✅ Show common errors and solutions
❌ Only show happy path

❌ 避けること

• 説明なしで専門用語を使う
• 読者が知識を持っていると決めつける
• 自分の視点（「私たち」「私たちの」）で書く
• エラーケースを省略する
• ドキュメントを古いままにする

---

ドキュメントのチェックリスト

はじめに

• インストール手順
• クイックスタートガイド
• Hello World の例
• 次のステップ

API ドキュメント

• 認証の説明
• すべてのエンドポイントのドキュメント
• リクエスト／レスポンスの例
• エラーコードの一覧
• レート制限の説明
• SDK のドキュメント

ガイド

• 一般的なユースケースを網羅
• ステップごとのチュートリアル
• スクリーンショット／動画を掲載
• トラブルシューティングのセクション

リファレンス

• すべてのパラメーターを記載
• 型を明記
• デフォルト値を一覧表示
• 例を掲載

メンテナンス

• バージョン管理
• 変更履歴を管理
• リンク切れを確認
• 四半期ごとにレビュー

---

関連リソース

スキル：

• api-designer - API ドキュメント
• frontend-builder - コンポーネントのドキュメント
• ux-designer - ユーザーガイド

ツール：

• Docusaurus
• Swagger/OpenAPI
• GitBook
• Mintlify

---

優れたドキュメント ＝ 開発者の満足 ＝ プロダクトの成功。 📖