テクニカルドキュメンテーションの基礎——書き方、構成、メンテナンスの原則

## アーキテクチャ概要

### システム構成

# OpenAPI 3.0 例
paths:
  /users/{id}:
    get:
      summary: ユーザー情報の取得
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: ユーザーが見つからない

## アラート：データベース接続数 90% 超過

### 概要
- **メトリクス**: `db.connections.current / db.connections.max`
- **閾値**: 90%
- **重大度**: High

### 即時対応
1. 接続数を確認：`SHOW STATUS LIKE 'Threads_connected';`
2. 長時間実行クエリを確認：`SHOW PROCESSLIST;`
3. 必要に応じて Kill: `KILL {process_id};`

### エスカレーション
- 15 分以内に復旧しない場合：DB チームに連絡
- 30 分以上：CTO に報告

# Project Name

## クイックスタート

### 前提条件
- Node.js 20+
- Docker Desktop
- PostgreSQL 15+

### セットアップ
```bash
git clone https://github.com/org/project.git
cd project
npm install
docker compose up -d db
npm run migrate
npm run dev

npm test           # 全テスト実行
npm run test:watch # ウォッチモード

## 目次

### はじめての方
- [概要](#概要)
- [クイックスタート](#クイックスタート)

### 開発を始める
- [セットアップ](#セットアップ)
- [開発フロー](#開発フロー)

### 詳細
- [アーキテクチャ](#アーキテクチャ)
- [API リファレンス](#api-リファレンス)

### 参照
- [FAQ](#faq)
- [用語集](#用語集)

### 使用例

#### 基本的な使い方
```javascript
// ユーザーを作成
const user = await createUser({
  name: '山田太郎',
  email: 'test@example.com'
});

try {
  const user = await createUser({ email: 'invalid' });
} catch (error) {
  if (error.code === 'INVALID_EMAIL') {
    // 適切なエラーメッセージを表示
  }
}

// メールアドレス検証がない
const user = await createUser({ name: 'test' });

# ドキュメントタイトル

| 項目 | 内容 |
|------|------|
| **バージョン** | 1.0.0 |
| **最終更新日** | 2025-07-25 |
| **所有者** | 開発チーム |
| **ステータス** | 承認済み |

## 概要

このドキュメントは XXX システムのアーキテクチャを説明します。
所要時間：15 分

## 目次

1. [概要](#概要)
2. [アーキテクチャ](#アーキテクチャ)
3. [コンポーネント](#コンポーネント)
4. [データフロー](#データフロー)
5. [付録](#付録)

## 変更履歴

| 日付 | バージョン | 変更内容 | 変更者 |
|------|-----------|---------|--------|
| 2025-01-15 | 1.0.0 | 初版 | 山田 |
| 2025-03-20 | 1.1.0 | マイクロサービス移行 | 佐藤 |
| 2025-07-25 | 1.2.0 | 監視システム追加 | 鈴木 |

<!-- Markdown 例 -->
# 見出し

これは段落です。**太字**や *イタリック* も使えます。

## コードブロック

```javascript
const hello = 'world';

# ❌ 悪い例：情報が散在
# README.md: セットアップ手順（旧）
# Wiki: セットアップ手順（新）
# コードコメント：設定値（別バージョン）

# ✅ 良い例：情報源を統一
# source-of-truth: docs/setup.md
# 自動生成：README.md（from docs/setup.md）

# GitHub Actions 例：ドキュメント CI
name: Docs CI
on: [push]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Check links
        run: npx markdown-link-check README.md

      - name: Check spelling
        run: npx cspell README.md

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

# ADR-001: データベースに PostgreSQL を採用

## 状態
承認済み

## 文脈
プロジェクト X では、リレーショナルデータベースが必要です。
候補として PostgreSQL、MySQL、Aurora が挙げられました。

## 決定
PostgreSQL を採用します。

## 根拠
1. **拡張性**: JSON 型、配列型など豊富なデータ型
2. **信頼性**: ACID 特性、トランザクション機能
3. **コミュニティ**: 活発な開発、豊富な情報

## トレードオフ
### 採用のメリット
- 複雑なクエリも実行可能
- データ整合性が高い

### 採用のデメリット
- MySQL よりセットアップが複雑
- 一部クラウドでマネージドオプションが少ない

## 参照
- [PostgreSQL 公式ドキュメント](https://www.postgresql.org/docs/)
- [比較記事：PostgreSQL vs MySQL](https://example.com/compare)

## 状態：廃止（2026-01-15）

代替技術の登場により、この決定は廃止されました。
新しい決定については ADR-015 を参照してください。

<!-- ❌ 完璧を目指して着手しない -->
「完璧なドキュメントを作らなければ」→ 1 行も書けない

<!-- ✅ MVP から始める -->
まずはクイックスタートだけ書く
→ 後から詳細を追加

## ドキュメント所有者

- **Primary**: @yamada
- **Secondary**: @sato
- **レビューサイクル**: 四半期に 1 回

<!-- ❌ 過剰な詳細 -->
# 全機能リファレンス（500 ページ）

<!-- ✅ 分離 -->
# クイックスタート（5 ページ）
# 機能ガイド（50 ページ）
# API リファレンス（別ドキュメント）

<!-- ❌ 専門用語のみ -->
「本サービスはマイクロサービスアーキテクチャに基づき、
イベント駆動型の CQRS パターンを実装しています」

<!-- ✅ 用語説明を追加 -->
「本サービスはマイクロサービスアーキテクチャ
（多数の独立したサービスで構成される設計）に基づき、
イベント駆動型（イベント発生時に処理が実行される方式）の
CQRS パターン（コマンドとクエリの責任を分離する設計）を
実装しています」

<!-- さらに用語集へのリンク -->
> 用語の詳細は [用語集](#用語集) を参照

# API ドキュメント：Swagger/OpenAPI
# コードから自動生成
openapi: 3.0.0
info:
  title: API Documentation
  version: 1.0.0

# コメントから生成（JSDoc 例）
/**
 * ユーザーを作成します
 * @param {Object} options - オプション
 * @param {string} options.email - メールアドレス
 * @returns {Promise<User>} 作成されたユーザー
 */

<!-- ❌ 抽象的 -->
「適切な設定を行ってください」

<!-- ✅ 具体的 -->
「`.env` ファイルに以下の行を追加してください：
DATABASE_URL=postgresql://localhost/mydb」

## ドキュメントレビューチェックリスト

### 技術的正確性
- [ ] 手順通りに動作するか
- [ ] コードサンプルは正しいか
- [ ] 設定値は最新か

### 可读性
- [ ] 専門用語は説明されているか
- [ ] 文は簡潔か
- [ ] 図解は適切か

### 完全性
- [ ] 必要な情報が揃っているか
- [ ] リンクは切れていないか
- [ ] 関連ドキュメントへのリンクはあるか