technical-writing（技术写作）

Technical Writing for Developers

Write clear, maintainable developer documentation — from README files to full documentation sites.

1. Documentation Strategy

1.1 Diataxis framework

Organize documentation into four distinct types:

                     PRACTICAL                 THEORETICAL
                 (steps to follow)          (understanding)
            ┌─────────────────────┬─────────────────────────┐
  LEARNING  │     Tutorials       │      Explanation         │
  (study)   │  "Learning-oriented"│  "Understanding-oriented"│
            │  Hand-held lessons  │  Background, context     │
            ├─────────────────────┼─────────────────────────┤
  WORKING   │    How-to Guides    │      Reference           │
  (apply)   │  "Task-oriented"    │  "Information-oriented"  │
            │  Solve a problem    │  Dry, accurate, complete │
            └─────────────────────┴─────────────────────────┘

1.2 Audience analysis

Before writing, answer:

1. Who is reading? (Beginner dev, senior engineer, DevOps, manager)
2. What do they know already? (Prerequisites, assumed knowledge)
3. Why are they reading? (Learn, solve problem, look up fact)
4. Where will they read? (IDE, phone, printed, terminal)

1.3 Documentation lifecycle

Create → Review (PR) → Publish → Maintain → Deprecate → Archive
                ↑                    │
                └────────────────────┘
                   (update cycle)

• Create: Write alongside the code it documents
• Review: Treat docs PRs like code PRs — review for accuracy and clarity
• Maintain: Update docs when code changes (enforce via CI)
• Deprecate: Mark outdated docs with warnings, link to replacements
• Archive: Move to an archive section rather than deleting

2. README Templates

2.1 Library / package README

# library-name

> One-line description of what this library does.

[![npm version](https://img.shields.io/npm/v/library-name)](https://www.npmjs.com/package/library-name)
[![CI](https://github.com/org/library-name/actions/workflows/ci.yml/badge.svg)](https://github.com/org/library-name/actions)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

## Features

- Feature one — brief description
- Feature two — brief description
- Feature three — brief description

## Installation

npm install library-name

## Quick Start

import { something } from "library-name";

const result = something({ option: true }); console.log(result);

## Usage

### Basic usage

// Minimal example showing the most common use case

### Advanced usage

// Example showing configuration options, edge cases, or composition

## API Reference

### `functionName(options)`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `option1` | `string` | — | Required. Description. |
| `option2` | `boolean` | `false` | Optional. Description. |

**Returns:** `ResultType` — Description of return value.

**Example:**

const result = functionName({ option1: "value" });

## Configuration

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `debug` | `boolean` | `false` | Enable debug logging |
| `timeout` | `number` | `5000` | Request timeout in ms |

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.

## License

[MIT](LICENSE)

2.2 CLI tool README

# my-cli

> One-line description of what the CLI does.

## Installation

npm

npm install -g my-cli

Homebrew

brew install my-cli

Binary

curl -fsSL https://get.my-cli.dev | sh

## Quick Start

Initialize a new project

my-cli init my-project

Run the main command

my-cli run --config config.yml

## Commands

### `my-cli init [name]`

Create a new project.

my-cli init my-project --template minimal

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--template` | `-t` | `default` | Project template |
| `--force` | `-f` | `false` | Overwrite existing |

### `my-cli run`

Run the main process.

my-cli run --config custom.yml --verbose

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--config` | `-c` | `config.yml` | Config file path |
| `--verbose` | `-v` | `false` | Verbose output |
| `--dry-run` | | `false` | Show what would happen |

## Configuration File

config.yml

output: dist verbose: false plugins: - name: plugin-a option: value

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `MY_CLI_CONFIG` | `config.yml` | Config file path |
| `MY_CLI_LOG_LEVEL` | `info` | Log level |

## Exit Codes

| Code | Meaning |
|------|---------|
| `0` | Success |
| `1` | General error |
| `2` | Invalid arguments |
| `3` | Config file not found |

2.3 API service README

# My API

> REST API for managing widgets.

**Base URL:** `https://api.example.com/v1`

## Authentication

All requests require a Bearer token:

curl -H "Authorization: Bearer YOUR_TOKEN" https://api.example.com/v1/widgets

## Quick Start

Create a widget

curl -X POST https://api.example.com/v1/widgets \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"name": "My Widget", "color": "blue"}'

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/widgets` | List all widgets |
| `POST` | `/widgets` | Create a widget |
| `GET` | `/widgets/:id` | Get a widget |
| `PATCH` | `/widgets/:id` | Update a widget |
| `DELETE` | `/widgets/:id` | Delete a widget |

## Error Responses

All errors follow RFC 7807:

{ "type": "https://api.example.com/errors/not-found", "title": "Not Found", "status": 404, "detail": "Widget with ID 'abc' not found" }

## Rate Limits

| Plan | Requests/minute |
|------|----------------|
| Free | 60 |
| Pro | 600 |

## SDKs

- [JavaScript](https://github.com/org/sdk-js)
- [Python](https://github.com/org/sdk-python)

## Running Locally

git clone https://github.com/org/my-api.git cd my-api cp .env.example .env docker compose up -d npm run dev

3. API Documentation

3.1 JSDoc / TSDoc patterns

/**
 * Fetches a user by their unique identifier.
 *
 * @param id - The unique user identifier (UUID format)
 * @returns The user object, or `null` if not found
 * @throws {AuthenticationError} If the request is not authenticated
 * @throws {RateLimitError} If the rate limit is exceeded
 *
 * @example
 * ```ts
 * const user = await getUser("550e8400-e29b-41d4-a716-446655440000");
 * if (user) {
 *   console.log(user.name);
 * }
 * ```
 *
 * @see {@link updateUser} for modifying user data
 * @since 1.2.0
 */
async function getUser(id: string): Promise<User | null> {
  // ...
}

3.2 Common JSDoc/TSDoc tags

3.3 Python docstrings (Google style)

def create_order(
    user_id: str,
    items: list[OrderItem],
    *,
    discount_code: str | None = None,
) -> Order:
    """Create a new order for the given user.

    Validates inventory availability, applies any discount codes,
    and calculates the final total including tax.

    Args:
        user_id: The unique identifier of the customer.
        items: List of items to include in the order. Must not be empty.
        discount_code: Optional promotional discount code.

    Returns:
        The created Order object with a generated order ID and
        calculated totals.

    Raises:
        ValueError: If items list is empty.
        InsufficientStockError: If any item exceeds available inventory.
        InvalidDiscountError: If the discount code is expired or invalid.

    Example:
        >>> order = create_order(
        ...     user_id="user_123",
        ...     items=[OrderItem(sku="WIDGET-1", quantity=2)],
        ...     discount_code="SAVE10",
        ... )
        >>> print(order.total)
        18.00
    """

3.4 Generating docs from code

4. Architecture Decision Records (ADRs)

4.1 Why ADRs matter

ADRs capture the why behind architectural decisions. Code shows what; ADRs explain why that approach was chosen over alternatives.

4.2 ADR template

# ADR-001: Use PostgreSQL as primary database

## Status

Accepted (2025-01-15)

<!-- Proposed | Accepted | Deprecated | Superseded by ADR-XXX -->

## Context

We need a primary database for our application that handles:
- Transactional data (orders, users, payments)
- Full-text search on product descriptions
- JSON data for flexible product attributes
- Expected scale: 10M rows, 1000 req/s

## Decision

We will use **PostgreSQL 16** as our primary database.

## Consequences

### Positive
- Strong ACID compliance for financial data
- Native JSONB support eliminates need for a separate document store
- Built-in full-text search with `tsvector` avoids Elasticsearch dependency
- Excellent tooling: pgAdmin, pg_stat_statements, EXPLAIN ANALYZE

### Negative
- Horizontal scaling requires additional tooling (Citus, read replicas)
- Team needs to learn PostgreSQL-specific features (vs MySQL familiarity)
- Hosting cost is higher than SQLite for development

### Neutral
- Migration from current SQLite prototype requires data migration script
- Need to set up connection pooling (PgBouncer) for production

## Alternatives Considered

### MySQL 8
- Rejected: weaker JSON support, no native full-text search ranking

### MongoDB
- Rejected: eventual consistency not suitable for financial transactions

### SQLite
- Rejected: no concurrent write support for multi-server deployment

4.3 ADR file organization

docs/
  adr/
    index.md            # Table of contents
    0001-use-postgresql.md
    0002-adopt-event-sourcing.md
    0003-migrate-to-typescript.md
    template.md         # Copy this for new ADRs

4.4 ADR tooling

# adr-tools (shell-based)
brew install adr-tools
adr init docs/adr
adr new "Use PostgreSQL as primary database"
adr list

# Log4brains (web-based viewer)
npm install -g log4brains
log4brains init
log4brains adr new "Use PostgreSQL"
log4brains preview  # Opens browser

5. RFCs (Request for Comments)

5.1 RFC vs ADR

5.2 RFC template

# RFC: Implement Real-Time Notifications System

**Author:** Jane Smith
**Date:** 2025-02-01
**Status:** In Review
**Reviewers:** @backend-team, @frontend-team

## Summary

Proposal to add real-time push notifications using WebSocket connections
and a Redis Pub/Sub backend, replacing the current polling approach.

## Motivation

Current polling-based notifications:
- Add 500ms latency to notification delivery
- Generate 2M unnecessary API requests per day
- Account for 15% of server load

Users have requested instant notifications in feedback surveys (Issue #234).

## Detailed Design

### Architecture

Client ←── WebSocket ──→ WS Server ←── Redis Pub/Sub ──→ App Server

### Connection Lifecycle

1. Client authenticates via REST API, receives JWT
2. Client opens WebSocket to `wss://ws.example.com` with JWT
3. Server validates JWT, subscribes to user's Redis channel
4. App server publishes events to Redis
5. WS server forwards events to connected client

### Message Format

{ "id": "evt_abc123", "type": "notification", "data": { "title": "New comment on your post", "body": "John replied to your post...", "url": "/posts/123#comment-456" }, "timestamp": "2025-02-01T12:00:00Z" }

### Reconnection Strategy

- Exponential backoff: 1s, 2s, 4s, 8s, max 30s
- Resume from last received event ID (server-side buffer: 5 min)

## Drawbacks

- Added infrastructure complexity (Redis, WS server)
- WebSocket connections consume server memory (~2KB per connection)
- Requires new monitoring and alerting

## Alternatives Considered

### Server-Sent Events (SSE)
Simpler but unidirectional. Would work for notifications but limits
future bidirectional features (typing indicators, presence).

### Long Polling
Lower infrastructure cost but still has latency and unnecessary requests.

### Third-Party Service (Pusher/Ably)
Lower maintenance but adds vendor dependency and per-message cost
that becomes expensive at scale.

## Rollout Plan

1. **Phase 1** (Week 1-2): Infrastructure setup, basic WS server
2. **Phase 2** (Week 3-4): Integration with notification service
3. **Phase 3** (Week 5): Frontend integration, A/B test vs polling
4. **Phase 4** (Week 6): Full rollout, deprecate polling

## Unresolved Questions

- Should we support notifications when the browser tab is in the background?
- What is the maximum number of concurrent connections we need to support?
- Should we persist notification history in a database or only in-memory?

6. Changelogs

6.1 Keep a Changelog format

# 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/).

## [Unreleased]

### Added
- Support for custom themes in dashboard

## [2.1.0] - 2025-02-15

### Added
- Export data as CSV from any table view (#234)
- Dark mode toggle in settings

### Changed
- Improved search performance by 3x with new indexing strategy
- Updated React from 18.2 to 19.0

### Fixed
- Fixed timezone display for users in UTC+ zones (#456)
- Resolved memory leak in WebSocket connection handler

## [2.0.0] - 2025-01-01

### Added
- Real-time notifications via WebSocket

### Changed
- **BREAKING:** Authentication now uses JWT instead of session cookies
- **BREAKING:** Minimum Node.js version is now 20

### Removed
- Removed deprecated `/api/v1/` endpoints (use `/api/v2/`)

### Security
- Updated `jsonwebtoken` to fix CVE-2024-XXXXX

[Unreleased]: https://github.com/org/repo/compare/v2.1.0...HEAD
[2.1.0]: https://github.com/org/repo/compare/v2.0.0...v2.1.0
[2.0.0]: https://github.com/org/repo/releases/tag/v2.0.0

6.2 Changelog categories

6.3 Automated changelogs

# release-please (Google) — generates changelog from conventional commits
npm install -D release-please

# changesets (Atlassian) — developer-authored change descriptions
npm install -D @changesets/cli
npx changeset init
npx changeset          # Create a changeset
npx changeset version  # Update versions + changelog
npx changeset publish  # Publish to npm

7. Runbooks and Playbooks

7.1 Incident response runbook template

# Runbook: Database Connection Pool Exhaustion

**Severity:** P1 (Service degradation)
**On-call team:** Backend
**Last updated:** 2025-02-01

## Symptoms

- Application returns HTTP 503 errors
- Logs show: `Error: Cannot acquire connection from pool`
- Database monitoring shows max connections reached
- Response times spike above 5s

## Diagnosis

### Step 1: Confirm the issue

Check active connections

psql -c "SELECT count(*) FROM pg_stat_activity WHERE state = 'active';"

Check connection limits

psql -c "SHOW max_connections;"

Check waiting connections

psql -c "SELECT count(*) FROM pg_stat_activity WHERE wait_event_type = 'Lock';"

### Step 2: Identify the cause

Find long-running queries

psql -c "SELECT pid, now() - query_start AS duration, query FROM pg_stat_activity WHERE state = 'active' AND now() - query_start > interval '30 seconds' ORDER BY duration DESC LIMIT 10;"

Check for idle-in-transaction connections

psql -c "SELECT count(*), state FROM pg_stat_activity GROUP BY state;"

### Step 3: Check application logs

Look for connection errors

journalctl -u my-app --since "1 hour ago" | grep -i "connection\|pool\|timeout"

## Remediation

### Immediate (stop the bleeding)

Kill idle connections older than 5 minutes

psql -c "SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE state = 'idle in transaction' AND now() - state_change > interval '5 minutes';"

Restart application to reset connection pool

sudo systemctl restart my-app

### Short-term (prevent recurrence)

1. Increase `max_connections` in PostgreSQL config
2. Add statement timeout: `SET statement_timeout = '30s';`
3. Configure PgBouncer connection pooling

### Long-term (root cause fix)

1. Audit all database queries for missing connection releases
2. Add connection pool monitoring to Grafana dashboard
3. Set up alerts for connection count > 80% of max

## Escalation

If not resolved within 30 minutes:
1. Page the database team: @db-oncall
2. Consider enabling read-only mode
3. Contact cloud provider support if infrastructure-related

## Post-Incident

- [ ] Write post-mortem within 48 hours
- [ ] File tickets for long-term fixes
- [ ] Update this runbook with lessons learned

7.2 Post-mortem template

# Post-Mortem: [Incident Title]

**Date:** 2025-02-15
**Duration:** 45 minutes (14:30 - 15:15 UTC)
**Severity:** P1
**Author:** Jane Smith

## Summary

Brief 2-3 sentence summary of what happened and the impact.

## Timeline (UTC)

| Time | Event |
|------|-------|
| 14:30 | Monitoring alert: HTTP 503 rate > 5% |
| 14:32 | On-call engineer acknowledged, began investigation |
| 14:38 | Identified database connection pool exhaustion |
| 14:42 | Killed idle-in-transaction connections |
| 14:45 | Restarted application pods |
| 14:50 | Error rate returned to normal |
| 15:15 | Incident officially resolved after monitoring period |

## Root Cause

A deployed migration added a new query that opened a transaction but
did not close it on one error path, causing connections to accumulate.

## Impact

- ~2,000 users experienced errors during the 20-minute peak
- 15% of API requests returned 503 errors
- No data loss occurred

## What Went Well

- Monitoring detected the issue within 2 minutes
- Runbook for connection pool exhaustion was accurate and up-to-date
- Team communication was clear in the incident Slack channel

## What Went Wrong

- The faulty migration passed code review without catching the missing connection release
- No automated test for connection leak scenarios
- Staging environment did not reproduce the issue (lower traffic)

## Action Items

| Action | Owner | Due Date | Ticket |
|--------|-------|----------|--------|
| Add connection leak test to CI | @john | 2025-02-22 | #789 |
| Add PgBouncer connection pooling | @jane | 2025-03-01 | #790 |
| Update migration review checklist | @team | 2025-02-18 | #791 |

8. Diagram-as-Code

8.1 Mermaid — Sequence diagram

sequenceDiagram participant C as Client participant A as API Gateway participant S as Auth Service participant D as Database

C->>A: POST /login {email, password} A->>S: Validate credentials S->>D: SELECT user WHERE email = ? D-->>S: User record S->>S: Verify password hash alt Valid credentials S-->>A: JWT token A-->>C: 200 {token, refreshToken} else Invalid credentials S-->>A: Authentication failed A-->>C: 401 Unauthorized end

8.2 Mermaid — Architecture (C4-style)

graph TB subgraph "Client Layer" WEB[Web App<br>React] MOB[Mobile App<br>React Native] end

subgraph "API Layer" GW[API Gateway<br>Nginx] AUTH[Auth Service<br>Node.js] API[Core API<br>FastAPI] end

subgraph "Data Layer" PG[(PostgreSQL)] RD[(Redis Cache)] S3[S3 Storage] end

WEB --> GW MOB --> GW GW --> AUTH GW --> API AUTH --> PG AUTH --> RD API --> PG API --> RD API --> S3

8.3 Mermaid — Entity Relationship

erDiagram USER ||--o{ ORDER : places USER { uuid id PK string email UK string name timestamp created_at } ORDER ||--|{ ORDER_ITEM : contains ORDER { uuid id PK uuid user_id FK decimal total string status } ORDER_ITEM }o--|| PRODUCT : references ORDER_ITEM { uuid id PK uuid order_id FK uuid product_id FK int quantity decimal price } PRODUCT { uuid id PK string name string category decimal price }

8.4 Mermaid — Flowchart

flowchart TD A[User submits form] --> B{Input valid?} B -->|Yes| C[Create record in DB] B -->|No| D[Show validation errors] D --> A C --> E{Email unique?} E -->|Yes| F[Send welcome email] E -->|No| G[Show duplicate error] G --> A F --> H[Redirect to dashboard]

8.5 Mermaid — State diagram

stateDiagram-v2 [*] --> Draft Draft --> InReview: Submit InReview --> Draft: Request Changes InReview --> Approved: Approve Approved --> Published: Publish Published --> Archived: Archive Draft --> Archived: Discard Archived --> [*]

8.6 D2 diagrams

# D2 architecture diagram
direction: right

client: Client {
  web: Web App
  mobile: Mobile App
}

api: API Layer {
  gateway: API Gateway
  auth: Auth Service
  core: Core API
}

data: Data Layer {
  pg: PostgreSQL {shape: cylinder}
  redis: Redis {shape: cylinder}
}

client.web -> api.gateway
client.mobile -> api.gateway
api.gateway -> api.auth
api.gateway -> api.core
api.auth -> data.pg
api.core -> data.pg
api.core -> data.redis

8.7 ASCII art diagrams (for inline code comments)

Request Flow:
                                                    
  Client ──→ Load Balancer ──→ App Server ──→ Database
    │              │               │              │
    │         (round-robin)   (connection     (pg_pool)
    │                          pooling)           │
    └──────── Response ←──── Response ←──── Query Result

9. Writing Style Guide

9.1 Core principles

9.2 Formatting conventions

9.3 Sentence structure

• One idea per sentence. Split long sentences at conjunctions.
• Lead with the action. "Run npm install" not "You need to run npm install"
• Put conditions before instructions. "If using TypeScript, add a tsconfig.json" not "Add a tsconfig.json if using TypeScript"
• Use numbered lists for sequential steps. Use bullet lists for unordered items.

9.4 Inclusive language

10. Documentation Site Generators

10.1 Comparison

10.2 Docusaurus quick start

npx create-docusaurus@latest my-docs classic --typescript
cd my-docs
npm start

my-docs/
├── docs/
│   ├── intro.md
│   ├── getting-started/
│   │   ├── installation.md
│   │   └── configuration.md
│   └── api/
│       └── reference.md
├── blog/
├── src/
│   └── pages/
├── docusaurus.config.ts
└── sidebars.ts

10.3 Starlight (Astro) quick start

npm create astro@latest -- --template starlight my-docs
cd my-docs
npm run dev

10.4 VitePress quick start

npx vitepress init
npm run docs:dev

11. Docs-as-Code Workflow

11.1 CI checks for documentation

# .github/workflows/docs.yml
name: Docs CI

on:
  pull_request:
    paths: ["docs/**", "**/*.md"]

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

      - name: Markdown lint
        uses: DavidAnson/markdownlint-cli2-action@v18
        with:
          globs: "**/*.md"

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

      - name: Check links
        uses: lycheeverse/lychee-action@v2
        with:
          args: --no-progress "docs/**/*.md"
          fail: true

      - name: Build docs
        run: npm run docs:build

11.2 markdownlint configuration

// .markdownlint.json
{
  "MD013": false,
  "MD033": { "allowed_elements": ["br", "details", "summary", "img"] },
  "MD041": false,
  "MD024": { "siblings_only": true }
}

11.3 cspell configuration

// cspell.json
{
  "version": "0.2",
  "language": "en",
  "words": [
    "docusaurus", "starlight", "vitepress", "mkdocs",
    "preconfigured", "monorepo", "runbook", "frontmatter"
  ],
  "ignorePaths": ["node_modules", "dist", "package-lock.json"]
}

12. Code Examples in Documentation

12.1 Principles

1. Runnable — examples should work if copy-pasted
2. Realistic — use domain-relevant variable names, not foo/bar
3. Progressive — start simple, add complexity gradually
4. Complete — show imports, setup, and cleanup
5. Tested — run examples in CI to prevent rot

12.2 Example structure

// BAD: incomplete, unrealistic
const x = await fn({ a: 1 });

// GOOD: complete, realistic, commented
import { createClient } from "@example/sdk";

// Initialize with your API key (get one at https://example.com/keys)
const client = createClient({
  apiKey: process.env.EXAMPLE_API_KEY!,
});

// Fetch a list of users with pagination
const users = await client.users.list({
  limit: 20,
  cursor: undefined, // First page
});

console.log(`Found ${users.total} users`);
for (const user of users.data) {
  console.log(`- ${user.name} (${user.email})`);
}

12.3 Testing code examples

# Extract code blocks from markdown and run them
npx ts-node scripts/test-examples.ts

# Or use doctest-style testing
# Python: pytest --doctest-modules
# Rust: cargo test --doc

13. Common Pitfalls