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

緩和策

即時対応（ポッドがクラッシュしている場合）

# 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