Technical Writing English Guide — How to Write Technical Documentation for Developers

• 1. Core Principles of Technical Writing
  • 5 Core Principles
  • Active Voice vs Passive Voice
  • Writing Concise Sentences
• 2. How to Write a README
  • README Checklist
• 3. Writing API Documentation
  • Endpoint Document Structure
  • Key Rules for API Documentation
• 4. Writing RFCs / Design Documents
• 5. Common English Mistakes and Corrections
  • Articles (a/an/the)
  • Prepositions
  • Easily Confused Expressions
• 6. Useful Expression Patterns
• 7. Quiz
• Quiz

1. Core Principles of Technical Writing

The goal of Technical Writing is for readers to understand quickly and accurately. Clarity takes priority over literary expression.

5 Core Principles

1. Use active voice — Default to active voice
2. Be concise — Remove unnecessary words
3. Use simple words — Choose easy vocabulary
4. One idea per sentence — One idea per sentence
5. Use consistent terminology — Maintain terminology consistency

Active Voice vs Passive Voice

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.

Writing Concise Sentences

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. How to Write a README

Structure of a good 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 Checklist

• Does a single line explain what the project does?
• Can someone get it running within 30 seconds using the Quick Start?
• Are the installation instructions clear?
• Do the code examples work when copied and pasted?

3. Writing API Documentation

Endpoint Document Structure

## 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 |

Key Rules for API Documentation

• Specify type and required/optional status for all fields
• Provide working examples
• Document all error responses
• Include curl examples

# curl example
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. Writing RFCs / Design Documents

# 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. Common English Mistakes and Corrections

Articles (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.

Prepositions

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.

Easily Confused Expressions

# affect vs effect
The change affects performance. (verb: to influence)
The change has an effect on performance. (noun: influence)

# ensure vs insure
Ensure the server is running. (to make certain)
Insure is used only for insurance-related contexts.

# its vs it's
The system checks its configuration. (possessive)
It's important to validate input. (contraction of "it is")

# i.e. vs e.g.
Use a fast language (e.g., Go, Rust). (for example)
Use the default port (i.e., 8080). (that is, in other words)

6. Useful Expression Patterns

# Describing behavior
"This endpoint returns..." (This endpoint returns...)
"The function takes X as input and returns Y."
"If the request fails, the system retries up to 3 times."

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

# Versioning/Changes
"Added in v2.1.0"
"Deprecated since v3.0. Use X instead."
"Breaking change: The response format has changed."

7. Quiz

Quiz