documentation

文档

概述

文档作为一等工程产物。良好的文档可减少上手时间、支持工单和认知负担。

---

文档类型

类型	受众	目的	更新频率
README	新开发者	快速开始	每次重大变更
API 文档	API 使用者	参考	每次 API 变更
架构	团队	设计决策	每次设计变更
运行手册	运维	事件响应	每次事件
教程	用户	学习	定期

---

README 最佳实践

结构

# Project Name

> One-line description of what this project does.

[![Build Status](badge)](link)
[![Coverage](badge)](link)
[![License](badge)](link)

## Features

- Feature 1: Brief description
- Feature 2: Brief description
- Feature 3: Brief description

## Quick Start

```bash
# Install
npm install my-project

# Configure
export API_KEY=your-key

# Run
npx my-project start

安装

前置条件

• Node.js 18+
• PostgreSQL 15+

步骤

1. 克隆仓库
2. 安装依赖：npm install
3. 将 .env.example 复制为 .env
4. 运行迁移：npm run db:migrate
5. 启动服务：npm start

用法

基本示例

import { Client } from 'my-project';

const client = new Client({ apiKey: 'xxx' });
const result = await client.doSomething();

高级配置

[详细文档链接]

API 参考

[API 文档链接]

贡献

参见 CONTRIBUTING.md

许可证

MIT - 参见 LICENSE

---

## API Documentation

### OpenAPI/Swagger

```yaml
openapi: 3.0.3
info:
  title: User API
  description: |
    API for managing users.

    ## Authentication
    All endpoints require Bearer token authentication.

    ## Rate Limiting
    - 100 requests per minute per API key
    - 429 response when exceeded
  version: 1.0.0

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

paths:
  /users:
    get:
      summary: List users
      description: Returns a paginated list of users.
      operationId: listUsers
      tags:
        - Users
      parameters:
        - name: limit
          in: query
          description: Maximum number of users to return
          schema:
            type: integer
            default: 20
            maximum: 100
        - name: cursor
          in: query
          description: Pagination cursor from previous response
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserList'
              example:
                data:
                  - id: "usr_123"
                    email: "[email protected]"
                    name: "John Doe"
                meta:
                  hasMore: true
                  nextCursor: "eyJpZCI6MTIzfQ"
        '401':
          $ref: '#/components/responses/Unauthorized'

components:
  schemas:
    User:
      type: object
      required:
        - id
        - email
      properties:
        id:
          type: string
          description: Unique identifier
          example: "usr_123"
        email:
          type: string
          format: email
          description: User's email address
        name:
          type: string
          description: User's display name

  responses:
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: "Invalid or missing API key"

文档中的代码示例

## Creating a User

### Request

```bash
curl -X POST https://api.example.com/v1/users \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "name": "John Doe"
  }'

响应

{
  "id": "usr_123",
  "email": "[email protected]",
  "name": "John Doe",
  "createdAt": "2024-01-15T10:30:00Z"
}

错误响应

{
  "error": {
    "code": "validation_error",
    "message": "Invalid email format",
    "field": "email"
  }
}

---

## Architecture Decision Records (ADR)

### Template

```markdown
# ADR-001: Use PostgreSQL for Primary Database

## Status
Accepted

## Context
We need to choose a primary database for our application.
Requirements:
- ACID transactions
- Complex queries with joins
- Proven reliability at scale
- Good ecosystem and tooling

## Decision
We will use PostgreSQL as our primary database.

## Alternatives Considered

### MySQL
- Pros: Widely used, good performance
- Cons: Less feature-rich, weaker JSON support

### MongoDB
- Pros: Flexible schema, easy horizontal scaling
- Cons: No ACID transactions across documents, eventual consistency

### CockroachDB
- Pros: Distributed, PostgreSQL-compatible
- Cons: Higher operational complexity, newer technology

## Consequences

### Positive
- Strong consistency guarantees
- Rich query capabilities (CTEs, window functions)
- Excellent JSON support for semi-structured data
- Large community and ecosystem

### Negative
- Vertical scaling limits
- Need to manage read replicas for high read loads
- Schema migrations require careful planning

### Risks
- May need sharding solution if we exceed single-node capacity
- Team needs PostgreSQL expertise

## References
- [PostgreSQL Documentation](https://www.postgresql.org/docs/)
- [Internal benchmark results](link)

ADR 索引

# Architecture Decision Records

| ID | Title | Status | Date |
|----|-------|--------|------|
| [ADR-001](adr-001.md) | Use PostgreSQL | Accepted | 2024-01-01 |
| [ADR-002](adr-002.md) | JWT Authentication | Accepted | 2024-01-05 |
| [ADR-003](adr-003.md) | Microservices Split | Proposed | 2024-01-10 |
| [ADR-004](adr-004.md) | GraphQL vs REST | Superseded by ADR-006 | 2024-01-15 |

---

代码文档

JSDoc / TSDoc

/**
 * Calculates the total price including tax and discounts.
 *
 * @param items - Array of cart items
 * @param options - Calculation options
 * @returns The calculated price breakdown
 *
 * @example
 * ```typescript
 * const result = calculatePrice(
 *   [{ id: '1', price: 100, quantity: 2 }],
 *   { taxRate: 0.1, discountCode: 'SAVE10' }
 * );
 * console.log(result.total); // 198
 * ```
 *
 * @throws {ValidationError} If items array is empty
 * @throws {InvalidDiscountError} If discount code is invalid
 *
 * @see {@link applyDiscount} for discount logic
 * @since 2.0.0
 */
function calculatePrice(
  items: CartItem[],
  options: PriceOptions
): PriceBreakdown {
  // Implementation
}

/**
 * Represents a user in the system.
 *
 * @remarks
 * Users are created through the signup flow or admin panel.
 * Soft deletion is used - check `deletedAt` for active status.
 */
interface User {
  /** Unique identifier (UUID v4) */
  id: string;

  /** Email address (unique, validated format) */
  email: string;

  /**
   * User's display name
   * @defaultValue Derived from email if not provided
   */
  name?: string;

  /** Account creation timestamp */
  createdAt: Date;

  /** Soft deletion timestamp, null if active */
  deletedAt: Date | null;
}

行内注释

// ✅ Good: Explains WHY
// Use binary search because items are sorted and list can have 100k+ entries
const index = binarySearch(items, target);

// ✅ Good: Explains non-obvious behavior
// Sleep 100ms to avoid rate limiting from external API
await sleep(100);

// ✅ Good: Documents workaround
// HACK: Safari doesn't support this API, fall back to polyfill
// TODO: Remove when Safari 17 adoption > 90%
const result = window.api?.call() ?? polyfill();

// ❌ Bad: States the obvious
// Loop through users
for (const user of users) {

// ❌ Bad: Outdated comment
// Returns user's full name (actually returns email now)
function getUserIdentifier() {
  return user.email;
}

---

运行手册

结构

# Runbook: High Memory Usage Alert

## Overview
This runbook addresses alerts when application memory usage exceeds 80%.

## Prerequisites
- Access to Kubernetes cluster
- Permissions to view pods and logs
- Familiarity with application architecture

## Symptoms
- Alert: `HighMemoryUsage` firing
- Metric: `container_memory_usage_bytes` > 80% of limit
- Possible: OOMKilled pods, slow responses

## Diagnosis

### Step 1: Identify affected pods
```bash
kubectl top pods -n production | sort -k3 -rh | head -10

步骤 2：检查内存泄漏

# Get heap dump
kubectl exec -it <pod> -- node --heapsnapshot
kubectl cp <pod>:/app/heapsnapshot.heapsnapshot ./heapsnapshot.heapsnapshot

步骤 3：检查最近的部署

kubectl rollout history deployment/api -n production

缓解

立即措施（如果 Pod 正在崩溃）

# Scale up to distribute load
kubectl scale deployment/api --replicas=10

# Restart pods (rolling)
kubectl rollout restart deployment/api

如果确认存在内存泄漏

1. 从堆快照中定位泄漏的代码路径
2. 准备热修复
3. 按照标准流程部署修复

解决

• 内存使用率降至 70% 以下
• 30 分钟内无 OOMKilled 事件
• 告警自动解除

升级

• L1：值班工程师
• L2：平台团队（如果是基础设施问题）
• L3：应用团队负责人（如果是代码问题）

相关

• 内存分析指南
• 事件 INC-123 - 之前的内存泄漏

---

## Documentation Tools

| Tool | Use Case | Format |
|------|----------|--------|
| Docusaurus | Documentation sites | MDX |
| Swagger UI | API reference | OpenAPI |
| Storybook | Component docs | JSX/TSX |
| MkDocs | Technical docs | Markdown |
| Notion | Team wikis | Rich text |

---

## Related Skills

- [[api-design]] - API documentation
- [[code-quality]] - Self-documenting code
- [[reliability-engineering]] - Runbooks