Technical Writing 영어 가이드 — 개발자를 위한 기술 문서 작성법

• 1. Technical Writing의 핵심 원칙
  • 5가지 핵심 원칙
  • 능동태 vs 수동태
  • 간결한 문장 작성
• 2. README 작성법
  • README 체크리스트
• 3. API Documentation 작성
  • Endpoint 문서 구조
  • API 문서 핵심 규칙
• 4. RFC / Design Document 작성
• 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 — 문장당 하나의 아이디어
5. Use consistent terminology — 용어 일관성 유지

능동태 vs 수동태

❌ The configuration file is read by the application at startup.
✅ The application reads the configuration file at startup.

❌ The error was caused by an invalid parameter.
✅ An invalid parameter caused the error.

❌ It is recommended that you use environment variables.
✅ Use environment variables.

간결한 문장 작성

❌ In order to install the package, you need to run the following command.
✅ To install the package, run:

❌ It should be noted that this feature is currently experimental.
✅ Note: This feature is experimental.

❌ Due to the fact that the server is down, the API is unavailable.
✅ 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 체크리스트

• 프로젝트가 무엇인지 한 줄로 설명했는가?
• Quick Start로 30초 안에 실행할 수 있는가?
• 설치 방법이 명확한가?
• 코드 예제가 복사-붙여넣기로 동작하는가?

3. API Documentation 작성

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 / Design Document 작성

# 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% → 50% → 100%)

5. 흔한 영어 실수와 교정

관사 (a/an/the)

❌ Send request to server.
✅ Send a request to the server.

❌ The each container runs in own namespace.
✅ Each container runs in its own namespace.

❌ Install a Docker before running the app.
✅ Install Docker before running the app.

전치사

❌ The app depends from the database.
✅ The app depends on the database.

❌ This is different to the previous version.
✅ This is different from the previous version.

❌ The data is stored in the Redis.
✅ 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. 퀴즈