영어 테크니컬 라이팅: API 문서와 RFC 작성 실전 가이드 2026

openapi: 3.1.0
info:
  title: User Management API
  version: 2.1.0
  description: |
    Manages user accounts, authentication, and profile data.

    ## Authentication
    All endpoints require a Bearer token in the Authorization header.
    Obtain a token via `POST /auth/token`.

    ## Rate Limiting
    - Authenticated requests: 1000 requests per minute
    - Unauthenticated requests: 60 requests per minute
  contact:
    name: API Support
    email: api-support@example.com
    url: https://developer.example.com/support

servers:
  - url: https://api.example.com/v2
    description: Production
  - url: https://staging-api.example.com/v2
    description: Staging

paths:
  /users:
    get:
      operationId: listUsers
      summary: List all users
      description: |
        Returns a paginated list of users. Results are sorted by
        creation date in descending order by default.
      parameters:
        - name: page
          in: query
          description: Page number (1-indexed)
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: per_page
          in: query
          description: Number of results per page (max 100)
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: status
          in: query
          description: Filter by account status
          schema:
            type: string
            enum: [active, inactive, suspended]
      responses:
        '200':
          description: A paginated list of users
          headers:
            X-Total-Count:
              description: Total number of users matching the query
              schema:
                type: integer
            X-Rate-Limit-Remaining:
              description: Number of requests remaining in the current window
              schema:
                type: integer
          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'
        '429':
          $ref: '#/components/responses/RateLimited'

components:
  schemas:
    User:
      type: object
      required: [id, email, created_at]
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the user
          examples: ['550e8400-e29b-41d4-a716-446655440000']
        email:
          type: string
          format: email
          description: User's email address
        display_name:
          type: ['string', 'null']
          description: User's display name. Null if not set.
          maxLength: 100
        status:
          type: string
          enum: [active, inactive, suspended]
          description: Current account status
        created_at:
          type: string
          format: date-time
          description: Account creation timestamp (ISO 8601)

    Pagination:
      type: object
      properties:
        current_page:
          type: integer
        total_pages:
          type: integer
        total_count:
          type: integer

  responses:
    Unauthorized:
      description: Authentication credentials are missing or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: 'UNAUTHORIZED'
              message: 'Bearer token is missing or expired'

    RateLimited:
      description: Too many requests
      headers:
        Retry-After:
          description: Seconds to wait before retrying
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: 'RATE_LIMITED'
              message: 'Rate limit exceeded. Retry after 30 seconds.'

    Error:
      type: object
      required: [error]
      properties:
        error:
          type: object
          required: [code, message]
          properties:
            code:
              type: string
              description: Machine-readable error code
            message:
              type: string
              description: Human-readable error description
            details:
              type: array
              items:
                type: object
                properties:
                  field:
                    type: string
                  reason:
                    type: string

Good:  "List all users"
Good:  "Create a new payment intent"
Good:  "Delete a webhook endpoint"

Bad:   "This endpoint lists all users"
Bad:   "Getting user information"
Bad:   "User list"

Good:
  Returns a paginated list of users. Results are sorted by creation
  date in descending order by default. Only returns users within
  the authenticated organization's scope.

Bad:
  Gets users.

Good:
  per_page (integer) - Number of results per page.
  Minimum: 1, Maximum: 100, Default: 20

Bad:
  per_page (integer) - Page size.

# Error Response Documentation Template
errors:
  - code: 'VALIDATION_ERROR'
    status: 400
    description: 'Request body or query parameters failed validation'
    causes:
      - 'Required field is missing'
      - 'Field value exceeds maximum length'
      - 'Invalid enum value'
    example:
      error:
        code: 'VALIDATION_ERROR'
        message: 'Validation failed'
        details:
          - field: 'email'
            reason: 'must be a valid email address'
          - field: 'display_name'
            reason: 'must not exceed 100 characters'

  - code: 'RESOURCE_NOT_FOUND'
    status: 404
    description: 'The requested resource does not exist or you lack permission to access it'
    causes:
      - 'Resource was deleted'
      - 'Resource ID is malformed'
      - 'Resource belongs to a different organization'
    example:
      error:
        code: 'RESOURCE_NOT_FOUND'
        message: 'User 550e8400-e29b-41d4-a716-446655440000 not found'

  - code: 'CONFLICT'
    status: 409
    description: 'The request conflicts with the current state of the resource'
    causes:
      - 'Email address already registered'
      - 'Concurrent modification detected (stale ETag)'
    example:
      error:
        code: 'CONFLICT'
        message: 'A user with this email already exists'
        details:
          - field: 'email'
            reason: 'already_exists'

  - code: 'INTERNAL_ERROR'
    status: 500
    description: 'An unexpected server error occurred. The team has been notified.'
    causes:
      - 'Unhandled exception'
      - 'Downstream service failure'
    example:
      error:
        code: 'INTERNAL_ERROR'
        message: 'An internal error occurred. Reference ID: req_abc123'

# RFC: [Title]

- **Author(s):** [Names]
- **Status:** Draft | In Review | Accepted | Rejected | Superseded
- **Created:** YYYY-MM-DD
- **Last Updated:** YYYY-MM-DD
- **Reviewers:** [Names]
- **Decision Deadline:** YYYY-MM-DD

## Summary

[2-3 sentences describing the proposal. A reader should understand
the core idea after reading only this section.]

## Motivation

[Why is this change necessary? What problem does it solve?
Include data, metrics, or user feedback that supports the need.]

### Current State

[Describe the current system/process and its limitations.]

### Desired State

[Describe the target state after implementing this proposal.]

## Detailed Design

### Architecture Overview

[High-level architecture diagram or description]

### API Changes

[Any new or modified API endpoints, schemas, or contracts]

### Data Model Changes

[Database schema changes, migration strategy]

### Implementation Plan

[Phased rollout plan with milestones]

| Phase | Scope | Timeline | Success Criteria |
| ----- | ----- | -------- | ---------------- |
| 1     |       |          |                  |
| 2     |       |          |                  |

## Alternatives Considered

### Alternative 1: [Name]

[Description, pros, cons, and why it was not chosen]

### Alternative 2: [Name]

[Description, pros, cons, and why it was not chosen]

## Risks and Mitigations

| Risk | Likelihood | Impact | Mitigation |
| ---- | ---------- | ------ | ---------- |
|      |            |        |            |

## Security Considerations

[Authentication, authorization, data privacy impacts]

## Backward Compatibility

[Breaking changes, migration path, deprecation timeline]

## Observability

[Logging, monitoring, alerting changes needed]

## Open Questions

- [ ] [Question 1]
- [ ] [Question 2]

## References

- [Link to related RFC, design doc, or external resource]

Good Summary:
  This RFC proposes replacing our current Redis-based session store
  with a JWT-based stateless authentication system. This change
  reduces infrastructure costs by ~40% and eliminates the session
  store as a single point of failure.

Bad Summary:
  This document discusses authentication improvements.

# Project Name

[![Build Status](https://img.shields.io/github/actions/workflow/status/org/repo/ci.yml)](link)
[![npm version](https://img.shields.io/npm/v/package-name)](link)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](link)

One-line description: what it does and who it's for.

## Features

- **Feature 1** - Brief description
- **Feature 2** - Brief description
- **Feature 3** - Brief description

## Quick Start

### Prerequisites

- Node.js >= 18.0
- PostgreSQL >= 15

### Installation

npm install package-name

### Basic Usage

import Client from 'package-name';

const client = new Client({ apiKey: process.env.API_KEY });
const result = await client.doSomething({ param: 'value' });
console.log(result);

## Documentation

- [Getting Started Guide](docs/getting-started.md)
- [API Reference](docs/api-reference.md)
- [Configuration](docs/configuration.md)
- [Migration Guide](docs/migration.md)

## Contributing

We welcome contributions. Please read our
[Contributing Guide](CONTRIBUTING.md) before submitting a PR.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing`)
5. Open a Pull Request

## License

This project is licensed under the MIT License.
See [LICENSE](LICENSE) for details.

Passive OK: "The data is encrypted at rest using AES-256."
(누가 암호화하는지보다 암호화 사실 자체가 중요)

Passive OK: "Deprecated endpoints will be removed in v3.0."
(누가 제거하는지보다 제거 사실이 중요)

Before:
  In order to configure the database connection, it is necessary
  to set the DATABASE_URL environment variable prior to starting
  the application server.

After:
  Set the DATABASE_URL environment variable before starting the
  application server.

Inconsistent:
  "Click the Submit button." ... "Press the Send button."
  ... "Tap the Confirm button."

Consistent:
  "Click Submit." ... "Click Send." ... "Click Confirm."

Bad:  "Can configure by editing the config file."
Good: "You can configure the service by editing the config file."

Bad:  "Must restart after changing settings."
Good: "Restart the server after changing settings."

Bad:  "Send request to endpoint."
Good: "Send a request to the endpoint."

Bad:  "The each user has unique ID."
Good: "Each user has a unique ID."

Bad:  "Restart a server." (특정 서버를 가리킬 때)
Good: "Restart the server."

Bad:  "Please click the Save button."
Good: "Click Save."

Bad:  "Please note that this feature requires admin access."
Good: "This feature requires admin access."

Bad:  "Do the setup of the environment."
Good: "Set up the environment."

Bad:  "Perform the deletion of old records."
Good: "Delete old records."

Bad:  "Make a configuration change."
Good: "Change the configuration."

Bad:  "The client sends a request to the server. It processes
       the data and returns a response. It then parses the JSON."
       (It이 client인지 server인지 불명확)

Good: "The client sends a request to the server. The server
       processes the data and returns a response. The client
       then parses the JSON."

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/),
and this project adheres to [Semantic Versioning](https://semver.org/).

## [2.1.0] - 2026-03-01

### Added

- `GET /users` endpoint now supports `status` query parameter
  for filtering by account status (#234)
- Rate limit headers (`X-Rate-Limit-Remaining`) included in
  all responses (#241)

### Changed

- Default pagination size changed from 50 to 20 for improved
  response times (#238)
- Error response format unified across all endpoints to use
  the standard error schema (#240)

### Deprecated

- `GET /users/search` endpoint. Use `GET /users` with query
  parameters instead. Will be removed in v3.0. (#235)

### Fixed

- Fixed race condition in concurrent user updates that could
  cause data loss (#237)
- Corrected OpenAPI spec for `PATCH /users` to include
  `display_name` field (#239)

## [2.0.0] - 2026-02-15

### Removed

- Removed `GET /users/list` endpoint (deprecated since v1.5)
- Dropped support for API key authentication. Use Bearer
  tokens instead.

### Changed

- **BREAKING:** User ID format changed from integer to UUID

# .github/workflows/docs-lint.yml
name: Documentation Lint

on:
  pull_request:
    paths:
      - 'docs/**'
      - '*.md'
      - 'openapi/**'

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Lint prose with Vale
        uses: errata-ai/vale-action@v2
        with:
          files: docs/
          config: .vale.ini

      - name: Validate OpenAPI spec
        run: |
          npx @redocly/cli lint openapi/spec.yaml

      - name: Check for broken links
        uses: lycheeverse/lychee-action@v2
        with:
          args: --verbose docs/

      - name: Spell check
        uses: streetsidesoftware/cspell-action@v6
        with:
          files: 'docs/**/*.md'