Technical Writing英語ガイド — 開発者のための技術文書作成法

• 1. Technical Writingの核心原則
  • 5つの核心原則
  • 能動態 vs 受動態
  • 簡潔な文章の作成
• 2. READMEの書き方
  • READMEチェックリスト
• 3. APIドキュメントの作成
  • Endpointドキュメント構造
  • APIドキュメントの重要ルール
• 4. RFC / 設計ドキュメントの作成
• 5. よくある英語の間違いと修正
  • 冠詞 (a/an/the)
  • 前置詞
  • 混同しやすい表現
• 6. 便利な表現パターン
• 7. クイズ
• クイズ

1. Technical Writingの核心原則

Technical Writingの目標は読者が素早く正確に理解することです。文学的表現ではなく、明確さが最優先です。

5つの核心原則

1. Use active voice — 能動態を基本に
2. Be concise — 不要な言葉を削除
3. Use simple words — 簡単な単語を選択
4. One idea per sentence — 1文に1つのアイデア
5. Use consistent terminology — 用語の一貫性を維持

能動態 vs 受動態

Bad:  The configuration file is read by the application at startup.
Good: The application reads the configuration file at startup.

Bad:  The error was caused by an invalid parameter.
Good: An invalid parameter caused the error.

Bad:  It is recommended that you use environment variables.
Good: Use environment variables.

簡潔な文章の作成

Bad:  In order to install the package, you need to run the following command.
Good: To install the package, run:

Bad:  It should be noted that this feature is currently experimental.
Good: Note: This feature is experimental.

Bad:  Due to the fact that the server is down, the API is unavailable.
Good: The API is unavailable because the server is down.

2. READMEの書き方

良いREADMEの構造：

# Project Name

One-line description of what this project does.

## Quick Start

\`\`\`bash
pip install my-package
my-package init
\`\`\`

## Features

- Feature A: Brief description
- Feature B: Brief description

## Installation

### Prerequisites

- Python 3.10+
- Docker (optional)

### Install from PyPI

\`\`\`bash
pip install my-package
\`\`\`

## Usage

### Basic Example

\`\`\`python
from my_package import Client

client = Client(api_key="your-key")
result = client.process("input data")
print(result)
\`\`\`

## Configuration

| Variable  | Description                | Default  |
| --------- | -------------------------- | -------- |
| `API_KEY` | Your API key               | Required |
| `TIMEOUT` | Request timeout in seconds | `30`     |

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## License

MIT License. See [LICENSE](LICENSE) for details.

READMEチェックリスト

• プロジェクトが何かを1行で説明しているか？
• Quick Startで30秒以内に実行できるか？
• インストール方法は明確か？
• コード例はコピー&ペーストで動作するか？

3. APIドキュメントの作成

Endpointドキュメント構造

## Create User

Creates a new user account.

**Endpoint:** `POST /api/v1/users`

**Headers:**
| Header | Required | Description |
|--------|----------|-------------|
| Authorization | Yes | Bearer token |
| Content-Type | Yes | `application/json` |

**Request Body:**
\`\`\`json
{
"email": "user@example.com",
"name": "John Doe",
"role": "admin"
}
\`\`\`

| Field | Type   | Required | Description                         |
| ----- | ------ | -------- | ----------------------------------- |
| email | string | Yes      | Valid email address                 |
| name  | string | Yes      | 1-100 characters                    |
| role  | string | No       | `admin` or `user` (default: `user`) |

**Response (201 Created):**
\`\`\`json
{
"id": "usr_abc123",
"email": "user@example.com",
"name": "John Doe",
"role": "admin",
"created_at": "2026-03-03T12:00:00Z"
}
\`\`\`

**Errors:**
| Status | Code | Description |
|--------|------|-------------|
| 400 | `invalid_email` | Email format is invalid |
| 409 | `email_exists` | Email already registered |
| 429 | `rate_limited` | Too many requests |

APIドキュメントの重要ルール

• すべてのフィールドにタイプと必須かどうかを明記
• 実際に動作する例を提供
• エラーレスポンスをすべて文書化
• curlの例を含める

# curl例
curl -X POST https://api.example.com/v1/users \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "name": "John Doe"
  }'

4. RFC / 設計ドキュメントの作成

# RFC: Implement Rate Limiting

**Author:** Youngju Kim
**Status:** Draft
**Created:** 2026-03-03

## Summary

Add rate limiting to the API gateway to prevent abuse
and ensure fair usage across all clients.

## Motivation

Current system has no request limits. A single client
can consume all available resources, degrading service
for other users.

## Detailed Design

### Algorithm

Use the token bucket algorithm with per-client buckets.

### Configuration

- Default: 100 requests/minute per API key
- Burst: Up to 20 additional requests
- Headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`

### Storage

Store counters in Redis with TTL-based expiration.

## Alternatives Considered

1. **Fixed window**: Simple but allows burst at boundaries
2. **Sliding window**: More accurate but higher memory cost

## Risks

- Redis failure could block all requests
- Mitigation: Fall back to in-memory counters

## Timeline

- Week 1: Core implementation
- Week 2: Integration tests
- Week 3: Gradual rollout (10% then 50% then 100%)

5. よくある英語の間違いと修正

冠詞 (a/an/the)

Bad:  Send request to server.
Good: Send a request to the server.

Bad:  The each container runs in own namespace.
Good: Each container runs in its own namespace.

Bad:  Install a Docker before running the app.
Good: Install Docker before running the app.

前置詞

Bad:  The app depends from the database.
Good: The app depends on the database.

Bad:  This is different to the previous version.
Good: This is different from the previous version.

Bad:  The data is stored in the Redis.
Good: The data is stored in Redis.

混同しやすい表現

# affect vs effect
The change affects performance.（動詞：影響を与える）
The change has an effect on performance.（名詞：影響）

# ensure vs insure
Ensure the server is running.（確認する）
Insure は保険関連でのみ使用

# its vs it's
The system checks its configuration.（所有格）
It's important to validate input.（it isの短縮形）

# i.e. vs e.g.
Use a fast language (e.g., Go, Rust).（例えば）
Use the default port (i.e., 8080).（つまり、言い換えれば）

6. 便利な表現パターン

# 動作の説明
"This endpoint returns..."（このエンドポイントは〜を返します）
"The function takes X as input and returns Y."
"If the request fails, the system retries up to 3 times."

# 注意事項
"Note: This operation is irreversible."
"Warning: This will delete all data."
"Important: Back up your data before upgrading."

# バージョン/変更
"Added in v2.1.0"
"Deprecated since v3.0. Use X instead."
"Breaking change: The response format has changed."

7. クイズ

クイズ