- Authors
- Name
- Youngju Kim
- @fjvbn20031
- はじめに
- 1. なぜエンジニアにライティングが重要（じゅうよう）か
- 2. RFC（Request for Comments）
- 3. ADR（Architecture Decision Records）
- 4. APIドキュメント（OpenAPI / Swagger）
- 5. READMEの書（か）き方（かた）
- 6. CHANGELOGの書（か）き方（かた）
- 7. 技術（ぎじゅつ）ブログの書（か）き方（かた）
- 8. ダイアグラミング
- 9. Docs-as-Code
- 10. ドキュメンテーション文化（ぶんか）の事例（じれい）
- 実践（じっせん）クイズ
- ツール一覧（いちらん）
- 参考（さんこう）資料（しりょう）
はじめに
「コードは開発者（かいはつしゃ）がコンピュータに話（はな）す言葉（ことば）であり、ドキュメントは開発者（かいはつしゃ）が他（ほか）の開発者（かいはつしゃ）に話（はな）す言葉（ことば）である。」
ソフトウェアエンジニアにとって、ライティング能力（のうりょく）はなぜ重要（じゅうよう）なのでしょうか？コードをうまく書（か）くだけでは不十分（ふじゅうぶん）です。設計（せっけい）の決定（けってい）を説明（せつめい）し、APIをドキュメント化（か）し、RFCを作成（さくせい）してチームの合意（ごうい）を導（みちび）く能力（のうりょく）こそが、シニアエンジニアとジュニアエンジニアを分（わ）ける核心的（かくしんてき）な能力（のうりょく）です。
Stripe、GitLab、Netflixのような企業（きぎょう）が「ドキュメンテーション文化（ぶんか）」を核心的（かくしんてき）な価値（かち）として掲（かか）げる理由（りゆう）があります。良（よ）いドキュメントはオンボーディング時間（じかん）を短縮（たんしゅく）し、意思決定（いしけってい）を透明（とうめい）にし、組織（そしき）の知識（ちしき）を保存（ほぞん）します。
このガイドでは、開発者（かいはつしゃ）が知（し）るべき**すべてのタイプの技術文書（ぎじゅつぶんしょ）の書（か）き方（かた）**をカバーします。
1. なぜエンジニアにライティングが重要（じゅうよう）か
1.1 ライティングが生（う）む違（ちが）い
| 状況（じょうきょう） | ライティングなし | ライティングあり |
|---|---|---|
| 設計（せっけい）レビュー | 口頭（こうとう）説明（せつめい）、記憶（きおく）に依存（いぞん） | RFC文書（ぶんしょ）で非同期（ひどうき）レビュー |
| アーキテクチャ変更（へんこう） | 「なぜこうしたの？」の繰（く）り返（かえ）し | ADRでコンテキスト保存（ほぞん） |
| 新入社員（しんにゅうしゃいん）オンボーディング | 口伝（くでん）の不足（ふそく）した知識（ちしき） | README + アーキテクチャ文書（ぶんしょ） |
| 外部（がいぶ）API提供（ていきょう） | 「これどう使（つか）うの？」の繰（く）り返（かえ）し質問（しつもん） | OpenAPI + サンプルコード |
| 技術（ぎじゅつ）ブログ | チーム外部（がいぶ）に知（し）られない | ブランディング + 採用（さいよう）効果（こうか） |
1.2 良（よ）い技術文書（ぎじゅつぶんしょ）の4つの原則（げんそく）
- 正確性（せいかくせい）（Accuracy）: コードとドキュメントが一致（いっち）すること
- 簡潔性（かんけつせい）（Conciseness）: 不要（ふよう）な内容（ないよう）を削除（さくじょ）する
- 構造化（こうぞうか）（Structure）: 見出（みだ）し、リスト、表（ひょう）を活用（かつよう）してスキャンしやすくする
- 読者（どくしゃ）中心（ちゅうしん）（Reader-Focused）: まず読者（どくしゃ）を特定（とくてい）する
1.3 読者（どくしゃ）分析（ぶんせき）フレームワーク
文書（ぶんしょ）を書（か）く前（まえ）に必（かなら）ず読者（どくしゃ）を定義（ていぎ）してください：
読者分析チェックリスト：
- 読者の技術レベルは？（ジュニア/シニア/非開発者）
- 読者がすでに知っていることは何か？
- 読者がこの文書を読んでできるべきことは？
- 読者がどのような状況で読むか？（学習/参照/問題解決）
2. RFC（Request for Comments）
2.1 RFCとは？
RFCは技術的（ぎじゅつてき）な提案（ていあん）をドキュメント化（か）してチームメンバーからフィードバックを受（う）け、合意（ごうい）を導（みちび）くプロセスです。Google、Meta、Uberなどほとんどのビッグテック企業（きぎょう）で使用（しよう）されています。
RFCを書（か）くべき場合（ばあい）：
- 新（あたら）しいシステムやサービスの導入（どうにゅう）
- 既存（きそん）アーキテクチャの大規模（だいきぼ）な変更（へんこう）
- 複数（ふくすう）チームに影響（えいきょう）する技術的（ぎじゅつてき）決定（けってい）
- 新（あたら）しい標準（ひょうじゅん）やプロセスの導入（どうにゅう）
2.2 RFCテンプレート
# RFC-001: ユーザー通知システムの再設計
## メタデータ
- 作成者: 田中太郎
- 状態: Draft / In Review / Accepted / Rejected / Superseded
- 作成日: 2025-03-15
- レビュアー: 鈴木花子, 佐藤次郎, 高橋三郎
- 関連RFC: RFC-042（イベントシステム）
## 要約 (Summary)
現在のポーリング型通知システムをWebSocketベースの
リアルタイム通知システムに置き換え、レイテンシを
30秒から1秒以内に短縮します。
## 動機 (Motivation)
- 現在のシステムは30秒ごとにポーリング（高レイテンシ）
- ポーリングによる不要なAPIコールが全トラフィックの15%
- ユーザー満足度調査：42%が「通知が遅い」と不満
## 提案 (Proposal)
### 技術設計
WebSocketサーバーを導入し、イベント駆動型の
通知パイプラインを構築します。
### 代替案の検討 (Alternatives Considered)
1. SSE: 単方向のみ、双方向通信不可
2. ポーリング間隔縮小（5秒）: サーバー負荷6倍増
3. Long Polling: コネクション管理の複雑さ
### マイグレーション戦略
1. Phase 1: WebSocketサーバー構築と内部テスト（2週間）
2. Phase 2: 10%カナリアデプロイ（1週間）
3. Phase 3: 全体展開とポーリング削除（1週間）
## リスクと懸念事項
- WebSocketコネクション維持コスト
- ファイアウォール/プロキシ環境でのWebSocket制限
- モバイル環境でのバッテリー消費
## オープンクエスチョン
- Redis Pub/Sub vs Kafkaをメッセージブローカーとして使用するか？
- オフラインユーザー通知のキューイング戦略は？
2.3 RFCプロセスフロー
┌──────────┐ ┌───────────┐ ┌───────────┐ ┌──────────┐
│ Draft │ -> │ In Review │ -> │ Decision │ -> │ Accepted │
│ (作成) │ │ (レビュー) │ │ (会議) │ │ (承認) │
└──────────┘ └───────────┘ └───────────┘ └──────────┘
│ │
v v
┌───────────┐ ┌────────────┐
│ Revision │ │ Superseded │
│ (修正) │ │ (置換) │
└───────────┘ └────────────┘
2.4 RFCレビューチェックリスト
## RFCレビューポイント
- [ ] 問題が明確に定義されているか？
- [ ] 提案が問題を実際に解決するか？
- [ ] 代替案が十分に検討されたか？
- [ ] マイグレーション戦略が現実的か？
- [ ] リスクが特定され緩和策があるか？
- [ ] 成功/失敗の測定基準があるか？
- [ ] ロールバック計画があるか？
3. ADR（Architecture Decision Records）
3.1 ADRとは？
ADRはアーキテクチャ意思決定（いしけってい）の**コンテキスト、理由（りゆう）、結果（けっか）**を記録（きろく）する短（みじか）い文書（ぶんしょ）です。Michael Nygardが提案（ていあん）したフォーマットが最（もっと）も広（ひろ）く使（つか）われています。
RFCとの違（ちが）い：RFCは「提案（ていあん）と議論（ぎろん）」、ADRは「決定記録（けっていきろく）」です。
3.2 ADRテンプレート（Michael Nygardフォーマット）
# ADR-007: PostgreSQLをプライマリデータベースとして選択
## ステータス (Status)
Accepted (2025-02-20)
## コンテキスト (Context)
新プロジェクトのプライマリデータベースを選択する必要があります。
主な要件：
- ACIDトランザクションサポート
- JSONデータ型のネイティブサポート
- 全文検索（Full-text search）機能
- チームの既存経験の活用
候補: PostgreSQL, MySQL 8.0, MongoDB, CockroachDB
## 決定 (Decision)
PostgreSQL 16をプライマリデータベースとして使用します。
理由：
1. JSONB型で半構造化データを効率的に処理可能
2. pg_trgm, ts_vectorで全文検索可能（別途Elasticsearch不要）
3. チームメンバー5人中4人がPostgreSQL経験あり
4. MVCCベースの同時実行制御が我々のワークロードに適合
## 結果 (Consequences)
肯定的：
- 単一データベースでリレーショナル + JSON + 検索処理
- 運用の複雑さ軽減（Elasticsearch不要）
- チーム学習コスト最小化
否定的：
- 水平スケーリングがMySQLより複雑
- Write-heavyワークロードでMVCCオーバーヘッドの可能性
- Citus等での拡張時に追加コスト
## 代替案 (Alternatives)
- MySQL 8.0: JSONサポートがPostgreSQL JSONBより限定的
- MongoDB: ACIDサポートは4.0からだが複雑なJOIN不可
- CockroachDB: 分散SQLだがチーム経験不足、運用コスト高
3.3 ADRディレクトリ構造（こうぞう）
docs/
└── adr/
├── 0001-use-react-for-frontend.md
├── 0002-adopt-typescript.md
├── 0003-choose-postgresql.md
├── 0004-implement-event-sourcing.md
├── 0005-migrate-to-kubernetes.md
├── 0006-adopt-graphql.md # Status: Superseded by 0010
├── 0007-choose-postgresql.md
├── 0008-use-redis-for-caching.md
├── 0009-adopt-trunk-based-dev.md
├── 0010-rest-api-over-graphql.md # Supersedes 0006
└── template.md
3.4 ADR自動化（じどうか）ツール
# adr-toolsのインストールと使用
brew install adr-tools
# 新しいADR作成
adr new "Use React for Frontend"
# -> docs/adr/0001-use-react-for-frontend.md を作成
# ADRの置き換え
adr new -s 6 "REST API over GraphQL"
# -> 0006のステータスをSupersededに変更
# 目次生成
adr generate toc
4. APIドキュメント（OpenAPI / Swagger）
4.1 OpenAPI 3.1仕様（しよう）の作成（さくせい）
openapi: 3.1.0
info:
title: User Management API
description: ユーザー管理のためのRESTful API
version: 2.1.0
contact:
name: Platform Team
email: platform@example.com
servers:
- url: https://api.example.com/v2
description: Production
- url: https://staging-api.example.com/v2
description: Staging
paths:
/users:
get:
summary: List all users
description: |
ページネーションをサポートするユーザー一覧取得APIです。
デフォルトではアクティブなユーザーのみ返します。
operationId: listUsers
tags:
- Users
parameters:
- name: page
in: query
description: ページ番号（1から開始）
schema:
type: integer
minimum: 1
default: 1
- name: limit
in: query
description: ページあたりのアイテム数
schema:
type: integer
minimum: 1
maximum: 100
default: 20
- name: status
in: query
description: ユーザーステータスフィルター
schema:
type: string
enum: [active, inactive, suspended]
default: active
responses:
'200':
description: 成功
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/User'
pagination:
$ref: '#/components/schemas/Pagination'
'401':
description: 認証失敗
'429':
description: レート制限超過
components:
schemas:
User:
type: object
required: [id, name, email, role, createdAt]
properties:
id:
type: string
description: ユーザー固有ID（usr_プレフィックス）
example: "usr_abc123"
name:
type: string
example: "Alice Kim"
email:
type: string
format: email
role:
type: string
enum: [admin, member, viewer]
createdAt:
type: string
format: date-time
Pagination:
type: object
properties:
page:
type: integer
limit:
type: integer
totalItems:
type: integer
totalPages:
type: integer
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
security:
- BearerAuth: []
4.2 APIドキュメントツール比較（ひかく）
| ツール | 特徴（とくちょう） | 推奨（すいしょう）状況（じょうきょう） |
|---|---|---|
| Swagger UI | OpenAPIレンダリング、インタラクティブテスト | クイックスタート |
| Redoc | きれいな3パネルレイアウト | 外部公開（こうかい）API |
| Stoplight | ビジュアルエディタ、モックサーバー | デザインファースト |
| Mintlify | MDXベース、美（うつく）しいUI | スタートアップ/OSS |
| ReadMe | ダッシュボード、分析（ぶんせき） | エンタープライズ |
4.3 良（よ）いAPIドキュメントのチェックリスト
## APIドキュメント品質チェックリスト
- [ ] すべてのエンドポイントに説明があるか？
- [ ] リクエスト/レスポンスの例があるか？
- [ ] エラーレスポンスとエラーコードが文書化されているか？
- [ ] 認証方法が明記されているか？
- [ ] レート制限情報が含まれているか？
- [ ] ページネーション方法が説明されているか？
- [ ] SDK/コード例が提供されているか？
- [ ] 変更履歴（changelog）が管理されているか？
5. READMEの書（か）き方（かた）
5.1 README構造（こうぞう）テンプレート
# プロジェクト名
簡潔な一行説明：このプロジェクトが何で、なぜ使うのか
  
## 主な機能 (Features)
## クイックスタート (Quick Start)
## インストール (Installation)
## 使い方 (Usage)
## 設定 (Configuration)
## APIリファレンス (API Reference)
## コントリビュート (Contributing)
## ライセンス (License)
5.2 README作成（さくせい）のコツ
30秒（びょう）ルール: 開発者（かいはつしゃ）がREADMEを開（ひら）いた時（とき）、30秒（びょう）以内（いない）に「このプロジェクトは自分（じぶん）に必要（ひつよう）か？」を判断（はんだん）できるべきです。
Bad README:
# my-project
Install and run.
Good README:
# FastCache
Redis互換インメモリキャッシュサーバー。Goで記述され、Redisと比較して
40%低いメモリ使用量を実現。
## なぜFastCacheか？
- Redisプロトコル100%互換 — 既存クライアントをそのまま使用
- メモリ使用量40%削減（ベンチマーク結果付き）
- シングルバイナリ、ゼロ依存
## 30秒スタート
(3行のインストール/実行コード)
6. CHANGELOGの書（か）き方（かた）
6.1 Keep a Changelogフォーマット
# Changelog
このプロジェクトのすべての主要な変更を記録します。
[Keep a Changelog](https://keepachangelog.com/) 形式に従います。
## [Unreleased]
### Added
- ダークモードサポート (#234)
- ユーザープロフィール画像アップロード機能 (#256)
## [2.1.0] - 2025-03-01
### Added
- WebSocketベースのリアルタイム通知システム (#189)
- 管理者ダッシュボード分析チャート (#201)
### Changed
- JWTトークン有効期限を24時間から12時間に変更
### Fixed
- 同時ログイン時のセッション衝突バグ修正 (#220)
### Deprecated
- /api/v1 エンドポイント（v3.0で削除予定）
### Security
- 依存関係更新: lodash 4.17.21 (CVE-2021-23337)
6.2 セマンティックバージョニング（SemVer）
MAJOR.MINOR.PATCH
MAJOR: 互換性のないAPI変更（Breaking Change）
MINOR: 後方互換の新機能追加
PATCH: 後方互換のバグ修正
例：
1.0.0 -> 1.0.1 （バグ修正）
1.0.1 -> 1.1.0 （新機能追加）
1.1.0 -> 2.0.0 （Breaking Change）
7. 技術（ぎじゅつ）ブログの書（か）き方（かた）
7.1 技術（ぎじゅつ）ブログ記事（きじ）の構造（こうぞう）
1. タイトル (Title)
- 具体的で検索可能なキーワードを含む
- Bad: 「学んだこと」
- Good: 「PostgreSQLで100万行クエリを2秒から50msに最適化した方法」
2. 導入部 (Introduction)
- 問題定義：読者が共感できる状況
- 結果プレビュー：「この記事を読めばXができます」
3. 本文 (Body)
- 問題 -> 試行 -> 失敗 -> 解決のストーリー構造
- 実行可能なコード例
- 複雑な概念のダイアグラム化
4. 結論 (Conclusion)
- 核心的教訓の要約（3行以内）
- 次のステップ
5. 参考資料 (References)
7.2 技術（ぎじゅつ）ブログSEO
## SEOチェックリスト
- [ ] タイトルにコアキーワード含む（50〜60文字）
- [ ] メタディスクリプション作成（150〜160文字）
- [ ] H2/H3見出しに関連キーワード含む
- [ ] 画像にaltタグ追加
- [ ] 内部/外部リンク含む
- [ ] URLがクリーンでキーワード含む
- [ ] コードブロックにシンタックスハイライティング適用
7.3 技術（ぎじゅつ）ブログライティングのコツ
ストーリー構造（こうぞう）を活用（かつよう）：
「私たちのチームは毎日午後3時にサーバーがダウンする問題に直面していた。」（問題）
「最初はメモリリークだと思った。」（仮説）
「しかしプロファイリングの結果、問題はGCではなくコネクションプール枯渇だった。」（発見）
「コネクションプール設定を変更しモニタリングを追加した結果...」（解決）
「この経験から学んだ3つの教訓：」（教訓）
8. ダイアグラミング
8.1 Mermaid
Markdown内（ない）でダイアグラムを作成（さくせい）できるテキストベースのツールです。GitHub、GitLab、Notionなどでネイティブサポートされています。
シーケンスダイアグラム：
sequenceDiagram
participant Client
participant API Gateway
participant Auth Service
participant User Service
participant Database
Client->>API Gateway: POST /login
API Gateway->>Auth Service: Validate credentials
Auth Service->>Database: Query user
Database-->>Auth Service: User data
Auth Service-->>API Gateway: JWT token
API Gateway-->>Client: 200 OK + token
アーキテクチャダイアグラム：
graph TD
A[Client] --> B[Load Balancer]
B --> C[API Server 1]
B --> D[API Server 2]
C --> E[Redis Cache]
D --> E
C --> F[PostgreSQL Primary]
D --> F
F --> G[PostgreSQL Replica]
C --> H[Message Queue]
D --> H
H --> I[Worker 1]
H --> J[Worker 2]
ステートダイアグラム：
stateDiagram-v2
[*] --> Draft
Draft --> InReview: Submit for review
InReview --> Approved: All reviewers approve
InReview --> Draft: Changes requested
Approved --> Published: Deploy
Published --> Archived: Deprecate
Archived --> [*]
8.2 PlantUML
より複雑（ふくざつ）なダイアグラムに適（てき）したツールです。
@startuml
!theme plain
package "Frontend" {
[React App] as react
[Next.js SSR] as nextjs
}
package "Backend" {
[API Gateway] as gateway
[User Service] as user
[Order Service] as order
[Notification Service] as notif
}
package "Data" {
database "PostgreSQL" as pg
database "Redis" as redis
queue "Kafka" as kafka
}
react --> gateway
nextjs --> gateway
gateway --> user
gateway --> order
user --> pg
order --> pg
user --> redis
order --> kafka
kafka --> notif
@enduml
8.3 ダイアグラムツール比較（ひかく）
| ツール | タイプ | 長所（ちょうしょ） | 短所（たんしょ） |
|---|---|---|---|
| Mermaid | テキストベース | Git親和的（しんわてき）、Markdown統合（とうごう） | 複雑（ふくざつ）なレイアウト制限（せいげん） |
| PlantUML | テキストベース | 豊富（ほうふ）なダイアグラムタイプ | Javaランタイム必要（ひつよう） |
| D2 | テキストベース | モダンな文法（ぶんぽう）、きれいな出力（しゅつりょく） | エコシステムがまだ小（ちい）さい |
| Excalidraw | ビジュアル | 手書（てが）きスタイル、直感的（ちょっかんてき） | Git diff不可（ふか） |
| draw.io | ビジュアル | 無料（むりょう）、豊富（ほうふ）なテンプレート | XMLベースでdiff困難（こんなん） |
8.4 ダイアグラム作成（さくせい）の原則（げんそく）
- 適切（てきせつ）な抽象化（ちゅうしょうか）レベル: すべての詳細（しょうさい）を含（ふく）めず、伝（つた）えたい核心（かくしん）だけ
- 一貫（いっかん）した方向性（ほうこうせい）: データフローは左（ひだり）から右（みぎ）、または上（うえ）から下（した）へ
- ラベルの活用（かつよう）: 矢印（やじるし）に説明（せつめい）を付（つ）けて関係（かんけい）を明確（めいかく）に
- 色（いろ）の節制（せっせい）: 最大（さいだい）3〜4色（しょく）のみ使用（しよう）
- 凡例（はんれい）を含（ふく）める: 記号（きごう）と色（いろ）の意味（いみ）を説明（せつめい）
9. Docs-as-Code
9.1 Docs-as-Codeとは？
ドキュメントをコードのように管理（かんり）する方法論（ほうほうろん）です：
- バージョン管理（かんり）: Gitでドキュメント履歴（りれき）を追跡（ついせき）
- PRレビュー: ドキュメント変更（へんこう）もコードレビューのように
- CI/CD: ドキュメントのビルドとデプロイを自動化（じどうか）
- リンティング: 文法（ぶんぽう）、スタイルの自動（じどう）チェック
9.2 Docs-as-Codeツール比較（ひかく）
| ツール | 特徴（とくちょう） | 推奨（すいしょう）状況（じょうきょう） |
|---|---|---|
| Docusaurus | Reactベース、MDX、バージョニング | オープンソースプロジェクト |
| MkDocs (Material) | Pythonベース、きれいなUI | 社内（しゃない）ドキュメント |
| Mintlify | AIベース、美（うつく）しいテーマ | APIドキュメント、スタートアップ |
| GitBook | WYSIWYG、コラボレーション | 非開発者（ひかいはつしゃ）を含（ふく）むチーム |
| Astro Starlight | Astroベース、高速（こうそく） | パフォーマンス重視（じゅうし） |
9.3 ドキュメントリンティング
# .github/workflows/docs-lint.yml
name: Docs Lint
on: [pull_request]
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: markdownlint
uses: DavidAnson/markdownlint-cli2-action@v18
with:
globs: 'docs/**/*.md'
- name: vale (prose linter)
uses: errata-ai/vale-action@v2
with:
files: docs/
vale_flags: "--config=.vale.ini"
Vale設定（せってい）例（れい）：
# .vale.ini
StylesPath = .vale/styles
MinAlertLevel = suggestion
[*.md]
BasedOnStyles = Vale, Google
Google.Passive = warning
Google.We = warning
Google.Will = error
Vale.Terms = error
10. ドキュメンテーション文化（ぶんか）の事例（じれい）
10.1 Stripe
- すべてをドキュメント化（か）: 設計（せっけい）決定（けってい）、障害報告書（しょうがいほうこくしょ）、オンボーディングガイド
- ライティング文化（ぶんか）: ライティングスキルが昇進（しょうしん）基準（きじゅん）に含（ふく）まれる
- APIドキュメント: 業界（ぎょうかい）最高（さいこう）レベルのAPIドキュメント
10.2 GitLab
- ハンドブックファースト: すべてのプロセスをまずハンドブックにドキュメント化（か）
- パブリックハンドブック: 2,000ページ以上（いじょう）のオープンハンドブック
- すべてのコミュニケーションをドキュメント化（か）: ミーティングノート、意思決定（いしけってい）ログすべて公開（こうかい）
10.3 Netflix
- RFC文化（ぶんか）: 技術的（ぎじゅつてき）決定（けってい）にRFCプロセス必須（ひっす）
- ポストモーテム: 障害後（しょうがいご）の詳細（しょうさい）な事後（じご）分析（ぶんせき）文書（ぶんしょ）
- Paved Road: 推奨（すいしょう）技術（ぎじゅつ）スタックとパターンをドキュメント化（か）
10.4 Amazon
- 6ページメモ: パワーポイントの代（か）わりに6ページのナラティブ文書（ぶんしょ）
- PR/FAQ文書（ぶんしょ）: 新製品（しんせいひん）/機能（きのう）はプレスリリース形式（けいしき）で提案（ていあん）
- 逆方向（ぎゃくほうこう）作業（さぎょう）（Working Backwards）: 顧客（こきゃく）視点（してん）からドキュメントを開始（かいし）
10.5 ドキュメンテーション文化（ぶんか）の導入（どうにゅう）段階（だんかい）
ステージ1: README標準化（1〜2週間）
- すべてのリポジトリにREADMEテンプレートを適用
- PRチェックリストに「ドキュメント更新」項目を追加
ステージ2: ADR導入（2〜4週間）
- ADRテンプレートとディレクトリ構造を設定
- 主要なアーキテクチャ決定にADR作成を義務化
ステージ3: RFCプロセス導入（1〜2ヶ月）
- RFCテンプレートとレビュープロセスを確立
- 影響度の高い変更にRFCを必須化
ステージ4: Docs-as-Code（2〜3ヶ月）
- ドキュメントサイト構築（Docusaurus/MkDocs）
- CI/CDパイプラインにドキュメントビルド/デプロイを統合
- リンティング自動化（markdownlint, Vale）
ステージ5: 文化定着（継続）
- 良いドキュメントへの認識と報酬
- 定期的なライティングワークショップ
- 新入社員オンボーディングにドキュメント作成練習を含める
実践（じっせん）クイズ
クイズ1：このRFCの問題点（もんだいてん）を見（み）つけてください。
# RFC: 新システム
## 要約
新しいシステムを作ります。
## 提案
Redisを使います。
## 結論
これがいいです。
問題点（もんだいてん）:
- 動機（どうき）の欠如（けつじょ）: なぜ新（あたら）しいシステムが必要（ひつよう）か説明（せつめい）がない
- 代替案（だいたいあん）の検討（けんとう）なし: Redisのみ言及（げんきゅう）で他（ほか）の選択肢（せんたくし）と比較（ひかく）していない
- 具体的（ぐたいてき）な設計（せっけい）なし: 「何（なに）」はあるが「どのように」がない
- リスク分析（ぶんせき）なし: どんな危険（きけん）があるか、緩和策（かんわさく）は何（なに）か
- 成功（せいこう）基準（きじゅん）なし: どの指標（しひょう）で成功（せいこう）を測定（そくてい）するか
- マイグレーション戦略（せんりゃく）なし: どのように移行（いこう）するか
- メタデータなし: 作成者（さくせいしゃ）、レビュアー、ステータス情報（じょうほう）がない
クイズ2：このAPIエンドポイントのドキュメントを改善（かいぜん）してください。
## GET /users
ユーザーを取得します。
改善案（かいぜんあん）:
## GET /users
ページネーションでユーザー一覧を取得します。
デフォルトではアクティブなユーザーのみ返します。
### パラメータ
| 名前 | 位置 | 型 | 必須 | 説明 | デフォルト |
|------|------|------|------|------|--------|
| page | query | integer | No | ページ番号（1から） | 1 |
| limit | query | integer | No | ページあたり項目数（1-100） | 20 |
| status | query | string | No | ステータスフィルター | active |
### レスポンス例
**200 OK**
（JSONレスポンス例を含む）
### エラーレスポンス
| ステータスコード | 説明 | 解決方法 |
|-----------|------|----------|
| 401 | 認証トークンが欠落または期限切れ | Authorizationヘッダーに有効なトークンを含める |
| 429 | レート制限超過（100req/min） | Retry-Afterヘッダーを参照して再試行 |
クイズ3：このADRで欠（か）けている項目（こうもく）を見（み）つけてください。
# ADR-003: MongoDBの使用
## 決定
MongoDBを使用します。
欠（か）けている項目（こうもく）:
- ステータス: Proposed/Accepted/Deprecated等（とう）
- コンテキスト: どんな問題（もんだい）を解決（かいけつ）するための決定（けってい）か
- 結果（けっか）: 肯定的（こうていてき）/否定的（ひていてき）な影響（えいきょう）
- 代替案（だいたいあん）の検討（けんとう）: なぜ他（ほか）のオプションではなくMongoDBか
- 日付（ひづけ）: いつ決定（けってい）したか
- 理由（りゆう）: なぜMongoDBを選択（せんたく）したか具体的（ぐたいてき）な根拠（こんきょ）
クイズ4：READMEの30秒（びょう）ルールを適用（てきよう）してみましょう。
次（つぎ）のREADMEを30秒（びょう）以内（いない）に判断（はんだん）できるように改善（かいぜん）してください：
# project-x
Node.jsプロジェクトです。
改善案（かいぜんあん）:
# ProjectX - リアルタイム協同ホワイトボード
ブラウザベースのリアルタイムホワイトボードツール。WebSocketで
最大50人が同時にドローイング/ノート/ダイアグラム作業可能。
主な機能:
- リアルタイムマルチプレイヤー編集（50人同時接続）
- 無限キャンバス + ベクターベースレンダリング
- Slack/Notion連携
技術スタック: Next.js, WebSocket, Canvas API, PostgreSQL
クイックスタート:
(3行のインストール/実行コード)
クイズ5：Mermaidで次（つぎ）のアーキテクチャをダイアグラムで表現（ひょうげん）してください。
「クライアントがAPIゲートウェイを通（とお）して認証（にんしょう）サービスと商品（しょうひん）サービスにアクセスし、各（かく）サービスはそれぞれ別（べつ）のデータベースを使用（しよう）する。」
答（こた）え:
graph TD
A[Client] --> B[API Gateway]
B --> C[Auth Service]
B --> D[Product Service]
C --> E[(Auth DB)]
D --> F[(Product DB)]
- 各（かく）サービスの境界（きょうかい）が明確（めいかく）
- データベースがサービスごとに分離（ぶんり）（Database per Serviceパターン）
- API Gatewayが単一（たんいつ）の入口（いりぐち）として機能（きのう）
ツール一覧（いちらん）
ドキュメント作成（さくせい）ツール
| カテゴリ | ツール | 用途（ようと） |
|---|---|---|
| APIドキュメント | Swagger/Redoc/Stoplight | OpenAPIレンダリング |
| ドキュメントサイト | Docusaurus/MkDocs/Mintlify | 技術（ぎじゅつ）ドキュメントサイト |
| ダイアグラム | Mermaid/PlantUML/D2 | テキストベースダイアグラム |
| リンティング | markdownlint/Vale | ドキュメント品質（ひんしつ）自動（じどう）チェック |
| ADR管理（かんり） | adr-tools/log4brains | ADR作成（さくせい）/管理（かんり） |
| CHANGELOG | conventional-changelog/release-please | 変更（へんこう）ログ自動（じどう）生成（せいせい） |
| スクリーンショット | carbon.now.sh/ray.so | コードスクリーンショット生成（せいせい） |
| コラボレーション | Notion/Confluence/GitBook | チームドキュメント協業（きょうぎょう） |
参考（さんこう）資料（しりょう）
- "Docs for Developers" by Jared Bhatti et al. (2021)
- Google Technical Writing Course (developers.google.com/tech-writing)
- Michael Nygard, "Documenting Architecture Decisions" (2011)
- OpenAPI Specification 3.1.0 (spec.openapis.org)
- Keep a Changelog (keepachangelog.com)
- Semantic Versioning (semver.org)
- Mermaid.js Documentation (mermaid.js.org)
- GitLab Handbook (handbook.gitlab.com)
- Stripe Engineering Blog — "Writing Culture"
- Amazon's "Working Backwards" Methodology
- Docusaurus Documentation (docusaurus.io)
- Vale.sh — Prose Linter (vale.sh)
- PlantUML Documentation (plantuml.com)
- "The Diagramming Playbook" — Simon Brown (structurizr.com)