テクニカルライティング (Technical Writing) 完全ガイド

目次

1. はじめに
2. テクニカルライティングの歴史と背景
3. テクニカルライティングの基本原則
4. 読者分析とペルソナ設計
5. 情報設計とアーキテクチャ
6. ドキュメントタイプと構造
7. 文章スタイルとトーン
8. 文法・表記の統一ルール
9. 視覚的要素の活用
10. API ドキュメンテーション
11. ソフトウェアドキュメンテーション
12. Docs as Code アプローチ
13. ツールとプラットフォーム
14. マークアップ言語と記法
15. 国際化とローカライゼーション
16. レビューと品質管理
17. アクセシビリティ
18. SEOとディスカバラビリティ
19. メトリクスと改善プロセス
20. チーム運営とワークフロー
21. まとめ

---

1. はじめに

テクニカルライティングとは、技術的な情報を正確かつ明瞭に読者に伝えるための文書作成技術である。ソフトウェアのドキュメント、API リファレンス、ユーザーマニュアル、操作手順書、ホワイトペーパーなど、多様な形式の技術文書を対象とする。

優れたテクニカルライティングは、単に技術的な内容を書き下すだけではない。読者の知識レベル、目的、文脈を理解した上で、必要な情報を最短経路で届ける「情報のUXデザイン」である。

1.1 テクニカルライティングが重要な理由

ビジネス上の価値:
- サポートコストの削減（良いドキュメントは問い合わせを減らす）
- オンボーディング時間の短縮（新メンバーの立ち上がり加速）
- 製品の採用率向上（開発者向けドキュメントの品質が製品選定に影響）
- コンプライアンス対応（規制産業では正確な文書化が法的要件）
- ナレッジの保全（属人化を防ぎ組織知を蓄積）

開発チームにおける価値:
- コードの理解促進とメンテナビリティ向上
- チーム間のコミュニケーション効率化
- 意思決定の記録と追跡可能性の確保
- 技術的負債の可視化と管理

1.2 本記事の構成

本記事は以下の4つのパートで構成されている。

1. 基礎編（セクション2〜5）: テクニカルライティングの歴史、基本原則、読者分析、情報設計
2. 実践編（セクション6〜9）: ドキュメントタイプ、文章スタイル、表記ルール、視覚要素
3. 技術編（セクション10〜14）: API ドキュメント、ソフトウェアドキュメント、ツール、マークアップ言語
4. 運用編（セクション15〜20）: 国際化、品質管理、アクセシビリティ、SEO、メトリクス、チーム運営

---

2. テクニカルライティングの歴史と背景

2.1 テクニカルライティングの起源

テクニカルライティングの歴史は、産業革命期にまで遡る。機械の操作マニュアルや工業規格の文書が、最初期のテクニカルライティングとされる。

歴史的な流れ:
1900年代初頭  産業機械の操作マニュアル
1940年代     第二次世界大戦中の軍事技術文書の標準化
1950年代     コンピュータ技術の登場に伴うソフトウェアドキュメント
1960年代     STC（Society for Technical Communication）の発展
1970年代     構造化ドキュメントの概念登場（SGML）
1980年代     デスクトップパブリッシング革命
1990年代     Webの登場とオンラインヘルプの普及
2000年代     Wiki、Docs as Codeの台頭
2010年代     開発者体験（DX）とAPIドキュメントの重要性認知
2020年代     AI支援ライティング、自動ドキュメント生成

2.2 テクニカルライティングの進化

従来のテクニカルライティングは、紙の印刷物を前提とした静的な文書作成が中心であった。しかし現代では、以下のような変化が起きている。

従来のアプローチ	現代のアプローチ
紙の印刷物	Web ベースのドキュメント
静的なコンテンツ	インタラクティブなコンテンツ
専門のテクニカルライター	開発者も含む全員がライター
ワードプロセッサ	Docs as Code（Git, Markdown）
ウォーターフォール的な更新	継続的なドキュメント更新
集中管理	分散管理（コードリポジトリ内）
読者は受動的	読者はフィードバックを提供
一方向の情報提供	コミュニティ主導のドキュメント

2.3 テクニカルコミュニケーション標準

主要なテクニカルコミュニケーションの標準規格と指針を以下に示す。

標準規格・指針:
- DITA (Darwin Information Typing Architecture)
  → OASIS標準。トピックベースの構造化オーサリング
- DocBook
  → 技術ドキュメント向けXMLスキーマ
- S1000D
  → 防衛・航空宇宙産業向け技術出版物標準
- IEEE Std 1063
  → ソフトウェアユーザードキュメント標準
- ISO/IEC 26514
  → ソフトウェアユーザードキュメントの設計者・開発者向け要求事項
- Microsoft Manual of Style
  → Microsoft の技術文書スタイルガイド
- Google Developer Documentation Style Guide
  → Google の開発者向けドキュメントスタイルガイド
- Apple Style Guide
  → Apple の文書作成スタイルガイド

3. テクニカルライティングの基本原則

3.1 明瞭性（Clarity）

テクニカルライティングの最も重要な原則は「明瞭性」である。読者が一度読んだだけで内容を正確に理解できることを目指す。

明瞭性を高めるための指針:

1. 一文一義
   悪い例: このシステムはデータを収集し、分析を行い、
          その結果をダッシュボードに表示するとともに、
          異常値が検出された場合にはアラートを送信する。

   良い例: このシステムはデータを収集し、分析する。
          結果はダッシュボードに表示される。
          異常値を検出した場合、アラートを送信する。

2. 能動態を使用する
   悪い例: 設定ファイルがシステムによって読み込まれる。
   良い例: システムは設定ファイルを読み込む。

3. 具体的な表現を使用する
   悪い例: 処理にはある程度の時間がかかる場合がある。
   良い例: 処理には通常 2〜5 秒かかる。

4. 不要な修飾語を除去する
   悪い例: 非常に重要な基本的に不可欠な設定パラメータ
   良い例: 必須の設定パラメータ

3.2 正確性（Accuracy）

技術文書における正確性は信頼性の基盤である。

正確性を確保する方法:

1. 技術的事実の検証
   - コード例は実際に動作することを確認する
   - バージョン情報を明記する
   - コマンドの実行結果は実環境で検証する

2. 用語の正確な使用
   - 公式な用語を使用する（例: 「コンテナ」と「Docker」を混同しない）
   - 略語は初出時に正式名称を記載する
   - 業界標準の定義に従う

3. 日付と時間の明確化
   - 「最近」「近い将来」ではなく具体的な日付を記載
   - タイムゾーンを明記（例: 2024-01-15 10:00 JST）
   - 相対的な時間表現は避ける

4. 数値の精度
   - 単位を明記する（例: 100 MB, 5 秒, 1000 リクエスト/秒）
   - 概数と正確な値を区別する

3.3 簡潔性（Conciseness）

不要な情報を排除し、読者の時間を尊重する。

簡潔性を高めるテクニック:

1. 冗長な表現の排除
   悪い例: 〜することが可能です → 良い例: 〜できます
   悪い例: 〜という点に留意する必要がある → 良い例: 〜に注意する
   悪い例: 〜を実施する作業を行う → 良い例: 〜を実施する
   悪い例: 基本的には → （削除可能な場合が多い）

2. 繰り返しの除去
   同じ情報を複数箇所で繰り返さない。
   必要な場合はクロスリファレンス（相互参照）を使用する。

3. 段落の長さ
   - 1つの段落は1つの主題に集中する
   - 3〜5文程度を目安とする
   - 長い段落は分割するか箇条書きに変換する

3.4 一貫性（Consistency）

文書全体で用語、表記、書式を統一する。

一貫性を確保する領域:

1. 用語の統一
   - 同じ概念に対して同じ用語を使用する
   - 用語集（グロッサリー）を作成・維持する
   - 例: 「ユーザー」と「利用者」を混在させない

2. 表記の統一
   - 数字の表記（半角/全角、漢数字）
   - 日付のフォーマット（YYYY-MM-DD, YYYY/MM/DD）
   - 括弧の使い方（「」『』()（））
   - 句読点（、。vs ，．）

3. 書式の統一
   - 見出しのレベルと命名規則
   - コード例の記載方法
   - 注意書き・警告の表記方法
   - リストの書式（番号付き vs 箇条書き）

4. 構造の統一
   - 同種のドキュメントは同じテンプレートを使用
   - セクションの順序を統一

3.5 完全性（Completeness）

読者が目的を達成するために必要な情報をすべて提供する。

完全性のチェックポイント:

1. 前提条件の明示
   - 必要な環境（OS、ランタイム、バージョン）
   - 必要な権限やアクセス
   - 事前にインストールすべきツール
   - 必要な知識レベル

2. 手順の網羅性
   - 「当たり前」のステップも省略しない
   - エラーが発生した場合の対処法を記載
   - 期待される結果を各ステップに記載

3. 関連情報への参照
   - 前提知識への参照リンク
   - より詳細な情報への参照
   - 関連するトラブルシューティング

4. 更新履歴
   - ドキュメントの最終更新日
   - 対象バージョン
   - 変更点の概要

---

4. 読者分析とペルソナ設計

4.1 読者分析の重要性

テクニカルライティングにおいて、「誰に向けて書くか」は「何を書くか」と同等に重要である。読者分析を怠ると、専門家には冗長で初心者には難解な中途半端な文書が生まれる。

4.2 読者セグメンテーション

読者のセグメント例（ソフトウェアドキュメントの場合）:

1. 初心者（Getting Started）
   - 技術的な背景知識が限定的
   - 製品に初めて触れる
   - 「何ができるか」「どう始めるか」を知りたい
   - ステップバイステップのガイダンスが必要

2. 中級者（How-to Guide）
   - 基本的な概念は理解している
   - 特定のタスクを達成したい
   - 「〜するにはどうすればよいか」を知りたい
   - 実践的なコード例が必要

3. 上級者（Reference / Deep Dive）
   - 高度な技術知識を持つ
   - 詳細な仕様情報が必要
   - API リファレンス、設定パラメータ一覧
   - エッジケースやパフォーマンス特性に関心

4. 意思決定者（Overview / Comparison）
   - 技術選定や導入判断を行う
   - アーキテクチャの概要が必要
   - 他製品との比較情報
   - コスト、スケーラビリティ、セキュリティ

4.3 ペルソナ設計テンプレート

# テクニカルドキュメントのペルソナ例

ペルソナ名: "バックエンド太郎"
役割: バックエンドエンジニア（経験3年）
技術スタック:
  - 言語: Python, Java
  - フレームワーク: Django, Spring Boot
  - インフラ: AWS (EC2, S3, RDS)
  - ツール: Git, Docker, VS Code
知識レベル:
  - REST API: 上級
  - GraphQL: 初心者
  - Kubernetes: 中級
  - CI/CD: 中級
目的:
  - 新しいAPIフレームワークの導入検討
  - 既存システムとの統合方法の確認
  - パフォーマンス最適化のベストプラクティス
好みのドキュメント形式:
  - コード例が豊富
  - コピー&ペースト可能なスニペット
  - 実行可能なサンプルプロジェクト
苦手なドキュメント:
  - 理論のみで実例がない
  - 前提条件が不明瞭
  - 更新されていない古い情報

4.4 読者の知識レベルに応じた書き分け

同じ内容を異なる読者向けに書き分ける例:

■ 初心者向け（チュートリアル）:
  「Docker コンテナとは、アプリケーションとその動作に必要な
  すべてのファイルをまとめたパッケージです。
  コンテナを使うと、あなたのパソコンでも、サーバーでも、
  まったく同じ環境でアプリケーションを動かすことができます。

  まず、Docker Desktop をインストールしましょう。
  1. https://docker.com にアクセスします
  2. 'Download Docker Desktop' をクリックします
  3. ダウンロードしたファイルを実行します
  ..."

■ 中級者向け（ハウツーガイド）:
  「マルチステージビルドを使って Docker イメージを最適化する:

  ```dockerfile
  # ビルドステージ
  FROM node:18 AS builder
  WORKDIR /app
  COPY package*.json ./
  RUN npm ci
  COPY . .
  RUN npm run build

  # 本番ステージ
  FROM node:18-slim
  COPY --from=builder /app/dist /app
  CMD ["node", "/app/index.js"]
  ```"

■ 上級者向け（リファレンス）:
  「Docker Engine API v1.43
  POST /containers/create
  
  パラメータ:
  | フィールド | 型 | 説明 |
  |-----------|------|------|
  | Image | string | コンテナイメージ名 |
  | Cmd | []string | 実行コマンド |
  | HostConfig.Memory | int64 | メモリ制限(バイト) |
  | HostConfig.CpuShares | int64 | CPU配分の相対的な重み |
  ..."

---

5. 情報設計とアーキテクチャ

5.1 情報アーキテクチャの基本

情報アーキテクチャ（IA）とは、ドキュメント全体の構造と情報の配置を設計することである。

情報アーキテクチャの4つの柱:

1. 組織化（Organization）
   情報をカテゴリやグループに分類する

2. ラベリング（Labeling）
   カテゴリやページに適切な名前を付ける

3. ナビゲーション（Navigation）
   読者が目的の情報にたどり着ける経路を設計する

4. 検索（Search）
   キーワードで情報を見つけられるようにする

5.2 Diátaxis フレームワーク

Diátaxis は、テクニカルドキュメントを体系的に分類するフレームワークである。Daniele Procida によって提唱された。

                    実用的（Practical）
                         |
           チュートリアル  |  ハウツーガイド
           (Tutorials)    |  (How-to Guides)
                         |
  学習 ─────────────────────────────── 作業
  (Learning)             |            (Working)
                         |
           説明           |  リファレンス
           (Explanation)  |  (Reference)
                         |
                    理論的（Theoretical）

4つのドキュメントタイプ:

1. チュートリアル（Tutorials）
   - 学習指向
   - 初心者を手を取って導く
   - 「料理教室」のようなもの
   - 結果：読者がスキルを習得

2. ハウツーガイド（How-to Guides）
   - 問題解決指向
   - 特定の目標を達成する手順
   - 「レシピ」のようなもの
   - 結果：読者が特定のタスクを完了

3. リファレンス（Reference）
   - 情報指向
   - 技術的な詳細を正確に記述
   - 「百科事典」のようなもの
   - 結果：読者が正確な情報を取得

4. 説明（Explanation）
   - 理解指向
   - 背景知識や概念を解説
   - 「歴史書」のようなもの
   - 結果：読者が「なぜ」を理解

5.3 情報の階層構造設計

ドキュメントサイトの階層構造例:

docs/
├── getting-started/           # チュートリアル
│   ├── introduction.md
│   ├── installation.md
│   ├── quickstart.md
│   └── first-project.md
├── guides/                    # ハウツーガイド
│   ├── authentication.md
│   ├── data-migration.md
│   ├── performance-tuning.md
│   └── deployment.md
├── reference/                 # リファレンス
│   ├── api/
│   │   ├── endpoints.md
│   │   ├── authentication.md
│   │   └── error-codes.md
│   ├── configuration.md
│   ├── cli-commands.md
│   └── glossary.md
├── concepts/                  # 説明
│   ├── architecture.md
│   ├── data-model.md
│   ├── security-model.md
│   └── design-decisions.md
├── troubleshooting/           # トラブルシューティング
│   ├── common-errors.md
│   ├── faq.md
│   └── known-issues.md
└── changelog.md               # 変更履歴

5.4 ナビゲーション設計

効果的なナビゲーションの要素:

1. グローバルナビゲーション（サイト全体）
   - 主要なセクションへの常時アクセス可能なメニュー
   - 検索バー
   - バージョンセレクタ

2. ローカルナビゲーション（セクション内）
   - サイドバーの目次
   - パンくずリスト
   - ページ内目次（Table of Contents）

3. コンテキストナビゲーション（関連情報）
   - 「次のステップ」リンク
   - 「関連記事」セクション
   - 「参照」リンク

4. ユーティリティナビゲーション
   - バージョン切り替え
   - 言語切り替え
   - ダークモード/ライトモード切り替え
   - 「このページを編集」リンク

5.5 コンテンツマッピング

コンテンツマップの作成手順:

1. 読者のジャーニーを定義
   発見 → 評価 → 導入 → 学習 → 実装 → 運用 → トラブルシューティング

2. 各段階で必要な情報を洗い出し
   発見: 概要、特徴、ユースケース
   評価: 比較表、制限事項、価格
   導入: インストール手順、システム要件
   学習: チュートリアル、概念説明
   実装: API リファレンス、コード例
   運用: 監視、バックアップ、アップグレード
   トラブルシューティング: FAQ、エラーコード、診断手順

3. 情報の優先度を決定
   P0: なければ製品が使えない（インストール、基本操作）
   P1: 主要なユースケースをカバー（ガイド、API リファレンス）
   P2: 生産性を向上させる（ベストプラクティス、高度な設定）
   P3: あると嬉しい（設計思想、歴史的背景）

6. ドキュメントタイプと構造

6.1 チュートリアル

チュートリアルは、読者を手取り足取り導き、新しいスキルを習得させることを目的とする。

# チュートリアルのテンプレート

## タイトル: 〜を作ってみよう / 〜を始めよう

### はじめに
- このチュートリアルで何を学ぶか
- 完成するとどうなるか（スクリーンショットやデモ）
- 所要時間の目安

### 前提条件
- 必要なソフトウェアとバージョン
- 必要な知識レベル
- 事前に完了しておくべき手順

### ステップ 1: 環境のセットアップ
（具体的な手順と実行結果）

### ステップ 2: 基本的な機能の実装
（コード例と解説）

### ステップ 3: 動作確認
（期待される結果の画面キャプチャ付き）

...

### まとめ
- 何を学んだか
- 次のステップへのリンク

### トラブルシューティング
- よくある問題と解決方法

良いチュートリアルの特徴:

✓ 最初から最後まで通して動作する
✓ 各ステップで期待される結果が明示されている
✓ 脱線しない（1つの学習目標に集中）
✓ 最小限の説明で最大の成果を出す
✓ エラーが起きそうなポイントでフォローがある
✓ 完成品のソースコードが入手可能

✗ 途中でバージョン違いにより動かない
✗ 暗黙の前提条件がある
✗ 概念の説明に脱線する
✗ コピー&ペーストしても動かないコード例

6.2 ハウツーガイド

ハウツーガイドは、特定の問題を解決するための手順書である。

# ハウツーガイドのテンプレート

## タイトル: 〜する方法 / 〜のやり方

### 概要
- この手順で何が達成できるか（1〜2文）

### 前提条件
- 必要な環境・権限

### 手順

#### 1. 準備
説明と具体的な操作。

#### 2. 実行
コマンドやコード例。

#### 3. 確認
成功の確認方法。

### 注意事項
- 制限事項や既知の問題

### 関連情報
- 関連するガイドへのリンク

チュートリアルとハウツーガイドの違い:

チュートリアル:                ハウツーガイド:
- 学習が目的                  - 問題解決が目的
- 読者は初心者                - 読者はある程度の知識あり
- 最初から最後まで順に読む     - 必要な部分だけ読む
- 「料理教室」                - 「レシピ本」
- 「Reactの基礎を学ぼう」     - 「Reactでフォームバリデーションを実装する方法」

6.3 リファレンスドキュメント

リファレンスは、技術的な詳細を正確かつ網羅的に記述する。

# リファレンスのテンプレート（API エンドポイント）

## POST /api/v1/users

ユーザーを新規作成する。

### リクエスト

**ヘッダー**

| ヘッダー | 値 | 必須 |
|---------|-----|------|
| Content-Type | application/json | ✓ |
| Authorization | Bearer {token} | ✓ |

**ボディ**

| フィールド | 型 | 必須 | 説明 |
|-----------|------|------|------|
| name | string | ✓ | ユーザー名（1〜100文字） |
| email | string | ✓ | メールアドレス |
| role | string | - | ロール。デフォルト: "viewer" |

**リクエスト例**

```json
{
  "name": "田中太郎",
  "email": "tanaka@example.com",
  "role": "editor"
}

レスポンス

成功（201 Created）

{
  "id": "usr_abc123",
  "name": "田中太郎",
  "email": "tanaka@example.com",
  "role": "editor",
  "created_at": "2024-01-15T10:30:00Z"
}

エラーレスポンス

ステータス	コード	説明
400	INVALID_EMAIL	メールアドレスの形式が不正
409	EMAIL_EXISTS	メールアドレスが既に登録済み
401	UNAUTHORIZED	認証トークンが無効

### 6.4 コンセプトドキュメント（Explanation）

```markdown
# コンセプトドキュメントのテンプレート

## タイトル: 〜の仕組み / 〜とは / 〜について

### 概要
（この概念の要約。1段落で）

### 背景
（なぜこの概念が重要か、どのような問題を解決するか）

### 仕組み
（技術的な動作原理をわかりやすく解説）
（図やダイアグラムを活用）

### 設計思想
（なぜこのような設計にしたのか）
（代替案との比較）

### 制限事項とトレードオフ
（この設計で意図的に犠牲にしたもの）

### 関連概念
（理解を深めるための関連概念へのリンク）

6.5 トラブルシューティングガイド

# トラブルシューティングのテンプレート

## 問題: エラーメッセージや症状の説明

### 症状
- 具体的に何が起きるか
- エラーメッセージの全文

### 原因
この問題は以下の場合に発生する:
1. 原因 A
2. 原因 B
3. 原因 C

### 解決方法

#### 原因 A の場合
1. 手順 1
2. 手順 2
3. 確認方法

#### 原因 B の場合
1. 手順 1
2. 手順 2
3. 確認方法

### それでも解決しない場合
- 追加の診断手順
- サポートへの連絡方法
- 報告すべき情報（ログ、環境情報など）

---

7. 文章スタイルとトーン

7.1 テクニカルライティングの文体

技術文書に適した文体:

1. 簡潔・直接的
   ✗ 「〜していただければと思います」
   ✓ 「〜してください」

   ✗ 「〜することも可能であると考えられます」
   ✓ 「〜できます」

2. 能動態を基本とする
   ✗ 「ファイルはサーバーにアップロードされます」
   ✓ 「サーバーにファイルをアップロードします」

   ✗ 「設定が完了されると、サービスが開始されます」
   ✓ 「設定を完了すると、サービスが開始します」

3. 現在形を使用する
   ✗ 「このボタンをクリックすると、ダイアログが表示されるでしょう」
   ✓ 「このボタンをクリックすると、ダイアログが表示されます」

4. 二人称（「あなた」）を使用する
   ✗ 「ユーザーはダッシュボードからプロジェクトを作成できる」
   ✓ 「ダッシュボードからプロジェクトを作成できます」
   ✓ (英語の場合) "You can create a project from the dashboard."

7.2 トーンの設定

トーンスペクトル:

フォーマル ──────────────── カジュアル

学術論文    技術仕様書    ガイド    チュートリアル    ブログ記事

技術文書の推奨トーン:
- フレンドリーだが馴れ馴れしくない
- プロフェッショナルだが堅すぎない
- 自信があるが傲慢でない
- 助けを提供する姿勢

企業別のトーン例:
- Google: フレンドリーで実用的
- Apple: 簡潔でエレガント
- Microsoft: 包括的で支援的
- Stripe: 開発者目線で具体的
- AWS: 正確で網羅的

7.3 注意書きとアドモニション

情報の重要度に応じた注意書きの分類:

> **ℹ️ 注記（Note）**
> 補足的な情報。知っておくと便利だが、タスクの完了には必須ではない。

> **💡 ヒント（Tip）**
> 効率や品質を向上させるための提案。

> **⚠️ 注意（Warning / Caution）**
> この操作を誤ると問題が発生する可能性がある。注意して実行すること。

> **🚨 危険（Danger）**
> データの損失やセキュリティ上のリスクがある。十分に理解してから実行すること。

> **📌 重要（Important）**
> タスクを正しく完了するために不可欠な情報。

使用ガイドライン:
- 注意書きの多用は避ける（読者が無視するようになる）
- 1ページに 2〜3 個が目安
- 本文内で伝えられる情報はアドモニションに入れない
- 最も重要な情報は本文に組み込む

7.4 インクルーシブな言語

テクニカルライティングにおけるインクルーシブな表現:

避けるべき表現 → 推奨される表現:

master/slave → primary/replica, leader/follower
whitelist/blacklist → allowlist/blocklist, permit list/deny list
sanity check → validation check, confidence check
dummy value → placeholder value, sample value
kill (a process) → stop, terminate, end
native → built-in, integrated
abort → cancel, stop
crippled → limited, restricted

ジェンダーニュートラルな表現:
彼/彼女 → その人、担当者、ユーザー
(英語) he/she → they
(英語) mankind → humanity, people
(英語) man-hours → person-hours, staff-hours

8. 文法・表記の統一ルール

8.1 日本語テクニカルライティングの表記ルール

■ 漢字とひらがなの使い分け

ひらがなにする語（補助動詞・形式名詞等）:
  ✗ 設定して下さい → ✓ 設定してください
  ✗ 実行する事が出来ます → ✓ 実行することができます
  ✗ 問題無い → ✓ 問題ない
  ✗ 全て → ✓ すべて
  ✗ 予め → ✓ あらかじめ
  ✗ 但し → ✓ ただし
  ✗ 又は → ✓ または
  ✗ 及び → ✓ および
  ✗ 殆ど → ✓ ほとんど
  ✗ 即ち → ✓ すなわち

漢字にする語（専門用語・一般的な漢字語）:
  ✓ 設定、実行、確認、操作、構成、機能
  ✓ 有効、無効、完了、失敗、成功

■ カタカナ表記
  - 外来語はカタカナで表記
  - 長音符（ー）は基本的に付ける
    ✗ サーバ → ✓ サーバー
    ✗ ユーザ → ✓ ユーザー
    ✗ コンテナ → ✓ コンテナ（3音以下は付けない場合もある）
  - JIS Z 8301 に準拠するか、社内ガイドラインに従う

■ 数字の表記
  - 数値は半角アラビア数字を使用
    ✗ 三つの方法 → ✓ 3 つの方法
    ✗ ５個のファイル → ✓ 5 個のファイル
  - 数値と単位の間にスペースを入れる
    ✓ 100 MB, 5 秒, 3 個
  - 桁区切りはカンマを使用
    ✓ 1,000, 100,000

■ 記号の使い方
  - 括弧: （）は日本語、() は英数字・コード
  - 引用符: 「」は日本語の引用、" " はコード内の文字列
  - 中点: ・は並列要素の区切り
  - コロン: ：は定義や説明の前

8.2 英語テクニカルライティングの表記ルール

■ 大文字・小文字
  - タイトル: Title Case（主要な語の頭を大文字に）
    "Getting Started with Docker Containers"
  - 見出し: Sentence case（文頭のみ大文字）が現在の主流
    "Getting started with Docker containers"
  - UI要素: 画面表示通りに記載
    Click **Save** to save your changes.

■ 句読点
  - Oxford comma（シリアルカンマ）を使用する
    ✓ "red, green, and blue"
    ✗ "red, green and blue"
  - リストの各項目の末尾にピリオドを付けるかどうか統一する
  - コロンの後は大文字で始める（完全な文の場合）

■ 略語
  - 初出時にフルスペルと略語を記載
    "Application Programming Interface (API)"
  - 2回目以降は略語のみ使用
  - 広く知られた略語（URL, HTML, API）は初出時でも略語のみ可

■ 数字
  - 1〜9 はスペルアウト（one, two, ... nine）
  - 10以上はアラビア数字（10, 100, 1,000）
  - 文頭の数字はスペルアウト
  - 技術的な数値は常にアラビア数字
    "Set the timeout to 5 seconds."

8.3 スタイルガイドの作成

# スタイルガイドの構成例

1. 文体と声のトーン:
   - 二人称（あなた/you）を使用
   - 能動態を基本とする
   - 現在形を使用
   - 丁寧語（です/ます調）を使用

2. 用語集:
   - 統一用語の一覧
   - 使用禁止用語の一覧
   - 略語の展開リスト

3. 表記規則:
   - 数字の書き方
   - 日付のフォーマット（YYYY-MM-DD）
   - 時刻のフォーマット（HH:MM JST）
   - ファイル名の記載方法
   - コードの記載方法

4. 書式規則:
   - 見出しのレベルと命名規則
   - リストの使い方
   - テーブルの使い方
   - 画像のキャプションと代替テキスト
   - コードブロックの言語指定

5. 注意書き:
   - Note, Tip, Warning, Danger の使い分け
   - 各アドモニションの書式

6. リンクと参照:
   - 内部リンクの書式
   - 外部リンクの書式
   - バージョン番号の参照方法

---

9. 視覚的要素の活用

9.1 ダイアグラムと図表

図の種類と用途:

1. アーキテクチャ図
   用途: システム全体の構成を俯瞰
   ツール: Mermaid, PlantUML, draw.io, Excalidraw

2. シーケンス図
   用途: コンポーネント間の通信フローを可視化
   ツール: Mermaid, PlantUML, WebSequenceDiagrams

3. フローチャート
   用途: 処理フローや意思決定プロセスを可視化
   ツール: Mermaid, draw.io

4. ER図（Entity-Relationship）
   用途: データモデルの構造を表現
   ツール: Mermaid, dbdiagram.io

5. ネットワーク図
   用途: ネットワーク構成を可視化
   ツール: draw.io, Lucidchart

6. ワイヤーフレーム
   用途: UI/UXの設計を可視化
   ツール: Figma, Excalidraw

9.2 Mermaid によるダイアグラム例

# シーケンス図
​```mermaid
sequenceDiagram
    participant Client
    participant API Gateway
    participant Auth Service
    participant User Service
    participant Database

    Client->>API Gateway: POST /api/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
​```

# フローチャート
​```mermaid
flowchart TD
    A[リクエスト受信] --> B{認証済み?}
    B -->|Yes| C{権限チェック}
    B -->|No| D[401 Unauthorized]
    C -->|許可| E[処理実行]
    C -->|拒否| F[403 Forbidden]
    E --> G[レスポンス返却]
​```

# アーキテクチャ図
​```mermaid
graph LR
    subgraph クライアント
        A[Web Browser]
        B[Mobile App]
    end
    subgraph API層
        C[API Gateway]
        D[Load Balancer]
    end
    subgraph マイクロサービス
        E[User Service]
        F[Order Service]
        G[Payment Service]
    end
    subgraph データ層
        H[(PostgreSQL)]
        I[(Redis)]
        J[(Elasticsearch)]
    end

    A --> C
    B --> C
    C --> D
    D --> E
    D --> F
    D --> G
    E --> H
    F --> H
    G --> H
    E --> I
    F --> J
​```

9.3 コードブロックのベストプラクティス

コードブロックの書き方:

1. 言語を必ず指定する
   ✗ ```
   ✓ ```python

2. コメントで要点を説明する
   ```python
   # データベース接続の設定
   db = Database(
       host="localhost",    # ホスト名
       port=5432,           # ポート番号
       database="myapp",    # データベース名
   )

3. 実行可能なコードにする

   • インポート文を含める
   • 変数の定義を含める
   • 期待される出力をコメントで記載

4. ハイライト行を活用する（対応ツールの場合）

   def process(data):
       validated = validate(data)
       # 以下の3行が重要
       result = transform(validated)
       enriched = enrich(result)
       return save(enriched)
   

5. 差分表示を活用する

   - old_setting = "value1"
   + new_setting = "value2"
   

6. コマンドと出力を区別する

   $ kubectl get pods
   NAME                    READY   STATUS    RESTARTS   AGE
   web-app-5d4f8b6-x2j9m  1/1     Running   0          5m
   

### 9.4 テーブルの効果的な使用

```markdown
テーブルを使うべき場面:
- パラメータ一覧
- 機能比較
- ステータスコード一覧
- 設定値の説明

テーブルの書式ガイドライン:
- ヘッダー行は必須
- 列数は 3〜5 列程度が読みやすい
- 長いテキストはテーブル内に入れず、リンクで参照
- デフォルト値は明示する

良いテーブルの例:

| パラメータ | 型 | 必須 | デフォルト | 説明 |
|-----------|------|------|-----------|------|
| `host` | string | ✓ | - | 接続先ホスト名 |
| `port` | integer | - | `5432` | ポート番号 |
| `timeout` | integer | - | `30` | タイムアウト（秒） |
| `ssl` | boolean | - | `false` | SSL接続の有効化 |
| `pool_size` | integer | - | `10` | コネクションプール数 |

9.5 スクリーンショットの活用

スクリーンショットのガイドライン:

1. 撮影ルール
   - 必要最小限の範囲をキャプチャ
   - 個人情報やセンシティブ情報をマスク
   - 一貫したブラウザ/OS環境で撮影
   - 解像度を統一（Retina対応推奨）

2. アノテーション
   - 注目すべき箇所を赤枠やハイライトで示す
   - 番号付きの吹き出しで手順を示す
   - 矢印で操作の流れを示す

3. 代替テキスト
   - すべての画像に代替テキストを設定
   - 画像の内容を簡潔に説明
   - アクセシビリティのために必須

4. メンテナンス性
   - UIが変更されると古くなるため最小限に
   - 抽象的な図で代替できる場合はそちらを優先
   - スクリーンショットのソースファイルを管理

10. API ドキュメンテーション

10.1 API ドキュメントの構成要素

優れた API ドキュメントに必要な要素:

1. 概要（Overview）
   - API の目的と主要な機能
   - ユースケース
   - アーキテクチャ概要

2. 認証（Authentication）
   - 認証方式の説明（API キー、OAuth、JWT等）
   - トークンの取得手順
   - 認証ヘッダーの設定例

3. クイックスタート（Quick Start）
   - 最小限のコードで API を呼び出す例
   - 複数の言語でのサンプル

4. エンドポイントリファレンス
   - 全エンドポイントの一覧
   - 各エンドポイントの詳細（後述）

5. エラーハンドリング
   - エラーレスポンスの構造
   - エラーコード一覧と対処法

6. レート制限（Rate Limiting）
   - 制限値と対象
   - レート制限ヘッダーの説明
   - 制限に達した場合の対処法

7. バージョニング
   - バージョン管理方針
   - 破壊的変更の扱い
   - 非推奨（Deprecated）のスケジュール

8. SDK / クライアントライブラリ
   - 公式SDKの一覧と導入手順
   - コミュニティ製ライブラリ

9. 変更履歴（Changelog）
   - 各バージョンの変更内容
   - 移行ガイド

10.2 OpenAPI（Swagger）仕様

# OpenAPI 3.0 仕様の例
openapi: 3.0.3
info:
  title: ユーザー管理 API
  description: |
    ユーザーの作成、取得、更新、削除を行う REST API。
    ## 認証
    すべてのエンドポイントで Bearer トークン認証が必要です。
  version: 1.0.0
  contact:
    name: API サポート
    email: api-support@example.com

servers:
  - url: https://api.example.com/v1
    description: 本番環境
  - url: https://staging-api.example.com/v1
    description: ステージング環境

paths:
  /users:
    get:
      summary: ユーザー一覧の取得
      description: |
        登録されているユーザーの一覧を取得する。
        ページネーションに対応。
      operationId: listUsers
      tags:
        - Users
      parameters:
        - name: page
          in: query
          description: ページ番号（1始まり）
          schema:
            type: integer
            default: 1
            minimum: 1
        - name: per_page
          in: query
          description: 1ページあたりの件数
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 100
      responses:
        '200':
          description: ユーザー一覧
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      summary: ユーザーの作成
      description: 新しいユーザーを作成する。
      operationId: createUser
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
            example:
              name: "田中太郎"
              email: "tanaka@example.com"
              role: "editor"
      responses:
        '201':
          description: ユーザー作成成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          $ref: '#/components/responses/BadRequest'
        '409':
          description: メールアドレスが既に登録済み

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
          description: ユーザーID
          example: "usr_abc123"
        name:
          type: string
          description: ユーザー名
          example: "田中太郎"
        email:
          type: string
          format: email
          description: メールアドレス
        role:
          type: string
          enum: [viewer, editor, admin]
          description: ロール
        created_at:
          type: string
          format: date-time
          description: 作成日時

    CreateUserRequest:
      type: object
      required:
        - name
        - email
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
        email:
          type: string
          format: email
        role:
          type: string
          enum: [viewer, editor, admin]
          default: viewer

    Pagination:
      type: object
      properties:
        current_page:
          type: integer
        total_pages:
          type: integer
        total_count:
          type: integer
        per_page:
          type: integer

  responses:
    Unauthorized:
      description: 認証エラー
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: "UNAUTHORIZED"
              message:
                type: string
                example: "Invalid or expired token"

    BadRequest:
      description: リクエストが不正
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
              message:
                type: string
              details:
                type: array
                items:
                  type: object
                  properties:
                    field:
                      type: string
                    message:
                      type: string

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

security:
  - bearerAuth: []

10.3 API ドキュメントのベストプラクティス

1. Try it（実行可能な例）
   - インタラクティブな API コンソールを提供
   - cURL コマンド例を各エンドポイントに記載
   - 複数言語での SDK 使用例

2. コード例の充実
   ```bash
   # cURL
   curl -X POST https://api.example.com/v1/users \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "田中太郎",
       "email": "tanaka@example.com"
     }'

# Python
import requests

response = requests.post(
    "https://api.example.com/v1/users",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    json={
        "name": "田中太郎",
        "email": "tanaka@example.com"
    }
)
user = response.json()

// JavaScript (Node.js)
const response = await fetch("https://api.example.com/v1/users", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "田中太郎",
    email: "tanaka@example.com",
  }),
});
const user = await response.json();

3. エラーの詳細な記載
   • 各エラーコードの原因と対処法
   • リクエスト例とエラーレスポンス例のペア

---

## 11. ソフトウェアドキュメンテーション

### 11.1 README の構成

```markdown
# プロジェクト名

簡潔な説明文（1〜2文）

[![Build Status](badge-url)](ci-url)
[![License](badge-url)](license-url)
[![Version](badge-url)](release-url)

## 概要

プロジェクトの目的と主な特徴を 3〜5 文で説明。

## 特徴

- 特徴 1: 簡潔な説明
- 特徴 2: 簡潔な説明
- 特徴 3: 簡潔な説明

## クイックスタート

### 前提条件

- Node.js 18 以上
- npm 9 以上

### インストール

```bash
npm install your-package

基本的な使い方

const lib = require('your-package');
const result = lib.doSomething();
console.log(result);

ドキュメント

詳細なドキュメントは docs.example.com を参照。

コントリビューション

コントリビューションを歓迎します。 CONTRIBUTING.md を参照してください。

ライセンス

MIT

### 11.2 コードコメントの書き方

```python
# --- 良いコメントの例 ---

# なぜ（Why）を説明するコメント
# レート制限に引っかかることを避けるため、
# リクエスト間に100msの遅延を挿入する
time.sleep(0.1)

# 複雑なロジックの意図を説明
# ビットマスクでフラグを管理:
# bit 0: 読み取り権限
# bit 1: 書き込み権限
# bit 2: 実行権限
permissions = (read << 0) | (write << 1) | (execute << 2)

# 外部システムの制約を説明
# Stripe API は冪等キーを48時間保持するため、
# リトライは48時間以内に行う必要がある
idempotency_key = generate_key()


# --- 悪いコメントの例 ---

# 変数iに1を加える（何をしているかはコードを見ればわかる）
i = i + 1

# ユーザーを取得する（メソッド名から明らか）
user = get_user(user_id)

# TODO: あとで直す（何を？いつ？誰が？）

# --- docstring の書き方（Google スタイル） ---

def calculate_shipping_cost(
    weight: float,
    destination: str,
    express: bool = False,
) -> float:
    """配送料金を計算する。

    重量と配送先に基づいて配送料金を算出する。
    エクスプレス配送の場合、通常料金の 1.5 倍となる。

    Args:
        weight: 荷物の重量（kg）。0.1 以上 30.0 以下。
        destination: 配送先の国コード（ISO 3166-1 alpha-2）。
        express: エクスプレス配送を使用するかどうか。

    Returns:
        配送料金（日本円）。小数点以下は切り上げ。

    Raises:
        ValueError: weight が範囲外の場合。
        UnsupportedDestinationError: 対応していない配送先の場合。

    Examples:
        >>> calculate_shipping_cost(2.5, "JP")
        800.0
        >>> calculate_shipping_cost(2.5, "US", express=True)
        4500.0
    """

11.3 ADR（Architecture Decision Record）

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

## ステータス

承認済み（2024-01-15）

## コンテキスト

新規プロジェクトにおいて、メインデータベースを選定する必要がある。
要件:
- ACID トランザクション対応
- JSON データの効率的な格納と検索
- 全文検索機能
- 実績のある運用ツールとエコシステム

## 検討した選択肢

### 1. PostgreSQL
- 長所: JSONB対応、全文検索、拡張性、成熟したエコシステム
- 短所: 水平スケーリングは追加ツールが必要

### 2. MySQL
- 長所: 高いパフォーマンス、広い採用実績
- 短所: JSON操作がPostgreSQLに劣る、全文検索が限定的

### 3. MongoDB
- 長所: スキーマレス、水平スケーリングが容易
- 短所: ACID トランザクションの制限、一貫性モデルの複雑さ

## 決定

PostgreSQL を採用する。

## 理由

- JSONB 型により、構造化データと半構造化データの両方を
  効率的に扱える
- 内蔵の全文検索により、Elasticsearch 等の追加コンポーネントが
  当面は不要
- チームに PostgreSQL の運用経験者が複数いる
- 将来的なスケーリングには Citus や読み取りレプリカで対応可能

## 影響

- ORM は SQLAlchemy を使用（PostgreSQL 固有機能を活用）
- マイグレーションツールは Alembic を使用
- バックアップは pg_dump + WAL アーカイブの組み合わせ

11.4 変更履歴（CHANGELOG）

# Changelog

このプロジェクトは [Semantic Versioning](https://semver.org/) に準拠する。

## [2.1.0] - 2024-03-15

### 追加
- ユーザーのバルクインポート機能 (#234)
- WebSocket によるリアルタイム通知 (#256)

### 変更
- レスポンスのページネーション形式を cursor-based に変更 (#245)
- Node.js の最低バージョンを 18 に引き上げ (#250)

### 修正
- 大量データ取得時のメモリリーク (#261)
- タイムゾーン変換の不具合 (#258)

### 非推奨
- `GET /api/v1/users?offset=N` のオフセットベースページネーション。
  v3.0 で削除予定。代わりに cursor パラメータを使用してください。

## [2.0.0] - 2024-01-10

### 破壊的変更
- 認証方式を API キーから OAuth 2.0 に変更
- レスポンスの日付フォーマットを ISO 8601 に統一
- Python SDK の最低バージョンを 3.9 に引き上げ

### 移行ガイド
[v1 から v2 への移行ガイド](docs/migration-v2.md) を参照。

12. Docs as Code アプローチ

12.1 Docs as Code とは

Docs as Code とは、ドキュメントをソフトウェアのソースコードと同じツール・ワークフローで管理するアプローチである。

Docs as Code の原則:

1. プレーンテキスト形式で記述
   - Markdown, reStructuredText, AsciiDoc
   - バイナリフォーマット（Word, PDF）ではない

2. バージョン管理システムで管理
   - Git リポジトリに格納
   - 変更履歴の追跡
   - ブランチとマージ

3. コードレビューのプロセス
   - プルリクエスト（PR）でレビュー
   - CI/CD による自動チェック
   - マージ前の品質担保

4. 自動ビルドとデプロイ
   - 静的サイトジェネレーターでビルド
   - CI/CD パイプラインで自動デプロイ
   - プレビュー環境での確認

5. テストの自動化
   - リンク切れチェック
   - スペルチェック
   - スタイルガイド準拠チェック
   - コード例の動作確認

12.2 リポジトリ構成

# ドキュメント専用リポジトリの構成例

docs-repo/
├── .github/
│   └── workflows/
│       ├── build.yml          # ビルド & デプロイ
│       ├── preview.yml        # PR プレビュー
│       └── lint.yml           # リンター
├── docs/
│   ├── getting-started/
│   │   ├── index.md
│   │   ├── installation.md
│   │   └── quickstart.md
│   ├── guides/
│   │   ├── authentication.md
│   │   └── deployment.md
│   ├── reference/
│   │   ├── api.md
│   │   └── configuration.md
│   └── assets/
│       ├── images/
│       └── diagrams/
├── .markdownlint.json         # Markdown リンター設定
├── .vale.ini                  # 文体チェッカー設定
├── mkdocs.yml                 # MkDocs 設定
├── package.json               # Node.js ツールの依存関係
└── README.md

# ソースコードリポジトリ内にドキュメントを同居させる構成例

project-repo/
├── src/                       # ソースコード
├── tests/                     # テスト
├── docs/                      # ドキュメント
│   ├── architecture.md
│   ├── api-reference.md
│   └── deployment-guide.md
├── README.md
├── CONTRIBUTING.md
├── CHANGELOG.md
└── ADR/                       # Architecture Decision Records
    ├── 001-database-choice.md
    └── 002-auth-method.md

12.3 CI/CD パイプライン

# GitHub Actions: ドキュメントのビルドとデプロイ
name: Deploy Docs

on:
  push:
    branches: [main]
    paths: ['docs/**', 'mkdocs.yml']
  pull_request:
    paths: ['docs/**', 'mkdocs.yml']

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

      - name: Markdown Lint
        uses: DavidAnson/markdownlint-cli2-action@v14
        with:
          globs: 'docs/**/*.md'

      - name: Vale (文体チェック)
        uses: errata-ai/vale-action@v2
        with:
          files: docs/

      - name: リンク切れチェック
        uses: lycheeverse/lychee-action@v1
        with:
          args: --verbose docs/

  build:
    needs: lint
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'

      - name: Install dependencies
        run: pip install mkdocs-material

      - name: Build
        run: mkdocs build --strict

      - name: Deploy
        if: github.ref == 'refs/heads/main'
        run: mkdocs gh-deploy --force

# PR プレビュー環境の自動構築
name: PR Preview

on:
  pull_request:
    paths: ['docs/**']

jobs:
  preview:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pip install mkdocs-material
      - run: mkdocs build

      - name: Deploy Preview
        uses: rossjrw/pr-preview-action@v1
        with:
          source-dir: site/

12.4 品質チェックの自動化

// .markdownlint.json
{
  "MD013": { "line_length": 120 },
  "MD033": false,
  "MD041": true,
  "MD024": { "siblings_only": true },
  "MD029": { "style": "ordered" }
}

# .vale.ini
StylesPath = .vale/styles
MinAlertLevel = warning

[*.md]
BasedOnStyles = Vale, Google, write-good

# カスタムルール
[*.md]
Google.Passive = warning
Google.We = error
write-good.Weasel = warning
write-good.TooWordy = suggestion

---

13. ツールとプラットフォーム

13.1 静的サイトジェネレーター

ツール比較:

| ツール | 言語 | マークアップ | 特徴 |
|--------|------|------------|------|
| MkDocs (Material) | Python | Markdown | シンプル、美しいテーマ |
| Docusaurus | JavaScript | MDX | React ベース、ブログ機能 |
| Sphinx | Python | reStructuredText | Python 公式、高機能 |
| Hugo | Go | Markdown | 極めて高速なビルド |
| Astro Starlight | JavaScript | MDX/Markdown | モダン、高パフォーマンス |
| GitBook | SaaS | Markdown | ホスティング込み |
| Confluence | SaaS | WYSIWYG | エンタープライズ向け |
| Notion | SaaS | Blocks | 汎用性が高い |

13.2 MkDocs Material の設定例

# mkdocs.yml
site_name: MyProject Documentation
site_url: https://docs.example.com
repo_url: https://github.com/example/myproject

theme:
  name: material
  language: ja
  palette:
    - scheme: default
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-7
        name: ダークモードに切り替え
    - scheme: slate
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-4
        name: ライトモードに切り替え
  features:
    - navigation.instant        # SPA風ナビゲーション
    - navigation.tracking       # URL フラグメント自動更新
    - navigation.tabs           # タブナビゲーション
    - navigation.sections       # セクション展開
    - navigation.expand         # サイドバー自動展開
    - search.suggest            # 検索サジェスト
    - search.highlight          # 検索ハイライト
    - content.code.copy         # コードコピーボタン
    - content.code.annotate     # コードアノテーション
    - content.tabs.link         # タブの連動

plugins:
  - search:
      lang: ja
  - tags
  - git-revision-date-localized:
      type: iso_date

markdown_extensions:
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.tabbed:
      alternate_style: true
  - admonition
  - pymdownx.details
  - attr_list
  - md_in_html
  - toc:
      permalink: true

nav:
  - ホーム: index.md
  - はじめに:
    - getting-started/index.md
    - インストール: getting-started/installation.md
    - クイックスタート: getting-started/quickstart.md
  - ガイド:
    - guides/authentication.md
    - guides/deployment.md
  - リファレンス:
    - reference/api.md
    - reference/configuration.md
  - FAQ: faq.md

extra:
  version:
    provider: mike
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/example/myproject

13.3 Docusaurus の設定例

// docusaurus.config.js
const config = {
  title: 'MyProject',
  tagline: 'ドキュメントサイト',
  url: 'https://docs.example.com',
  baseUrl: '/',

  i18n: {
    defaultLocale: 'ja',
    locales: ['ja', 'en'],
  },

  presets: [
    ['classic', {
      docs: {
        sidebarPath: './sidebars.js',
        editUrl: 'https://github.com/example/myproject/edit/main/',
        showLastUpdateTime: true,
        showLastUpdateAuthor: true,
      },
      blog: {
        showReadingTime: true,
      },
      theme: {
        customCss: './src/css/custom.css',
      },
    }],
  ],

  themeConfig: {
    navbar: {
      title: 'MyProject',
      items: [
        { type: 'doc', docId: 'intro', label: 'ドキュメント' },
        { to: '/blog', label: 'ブログ' },
        { type: 'docsVersionDropdown' },
        { type: 'localeDropdown' },
        { href: 'https://github.com/example/myproject', label: 'GitHub' },
      ],
    },
    algolia: {
      appId: 'YOUR_APP_ID',
      apiKey: 'YOUR_API_KEY',
      indexName: 'myproject',
    },
    prism: {
      theme: require('prism-react-renderer/themes/github'),
      darkTheme: require('prism-react-renderer/themes/dracula'),
      additionalLanguages: ['bash', 'yaml', 'python', 'java'],
    },
  },
};

module.exports = config;

13.4 API ドキュメントツール

ツール比較:

| ツール | 入力形式 | 特徴 |
|--------|---------|------|
| Swagger UI | OpenAPI | インタラクティブ、Try it out機能 |
| Redoc | OpenAPI | 美しい3カラムレイアウト |
| Stoplight | OpenAPI | ビジュアルエディタ付き |
| Slate | Markdown | Stripe風の3カラムドキュメント |
| ReadMe | OpenAPI/Markdown | SaaS、メトリクス機能 |
| Postman | Collection | APIテスト環境との統合 |

14. マークアップ言語と記法

14.1 Markdown

# Markdown 基本記法

## 見出し
# H1
## H2
### H3

## テキスト装飾
**太字**, *イタリック*, ~~取り消し線~~, `インラインコード`

## リスト
- 箇条書き 1
- 箇条書き 2
  - ネスト

1. 番号付き 1
2. 番号付き 2

## リンクと画像
[リンクテキスト](https://example.com)
![代替テキスト](image.png)

## コードブロック
```python
print("Hello, World!")

テーブル

ヘッダー1	ヘッダー2
セル1	セル2

引用

引用テキスト

水平線

---

### 14.2 Markdown 拡張（GFM, MDX）

```markdown
# GitHub Flavored Markdown (GFM) 拡張

## タスクリスト
- [x] 完了タスク
- [ ] 未完了タスク

## 脚注
テキスト[^1]
[^1]: 脚注の内容

## テーブルの配置
| 左寄せ | 中央 | 右寄せ |
|:-------|:----:|-------:|
| AAA    | BBB  |    CCC |

## 自動リンク
https://example.com は自動でリンクになる

## 絵文字
:rocket: :tada: :warning:

# MDX（Markdown + JSX）

import { Callout } from '@components/Callout'

<Callout type="warning">
  これは警告メッセージです。
</Callout>

export const Highlight = ({children, color}) => (
  <span style={{ backgroundColor: color, padding: '0.2rem' }}>
    {children}
  </span>
)

<Highlight color="#25c2a0">重要なテキスト</Highlight>

14.3 reStructuredText

reStructuredText 基本記法
=========================

見出し
------

小見出し
^^^^^^^^

テキスト装飾
~~~~~~~~~~~~

**太字**, *イタリック*, ``インラインコード``

リスト
~~~~~~

* 箇条書き 1
* 箇条書き 2

  * ネスト

#. 番号付き 1
#. 番号付き 2

ディレクティブ
~~~~~~~~~~~~~~

.. note::
   注記の内容

.. warning::
   警告の内容

.. code-block:: python

   def hello():
       print("Hello, World!")

.. image:: path/to/image.png
   :alt: 代替テキスト
   :width: 600px

テーブル
~~~~~~~~

+----------+----------+
| ヘッダー1 | ヘッダー2 |
+==========+==========+
| セル1    | セル2    |
+----------+----------+

クロスリファレンス
~~~~~~~~~~~~~~~~~~

:ref:`ラベル名`
:doc:`ドキュメント名`
:func:`関数名`
:class:`クラス名`

14.4 AsciiDoc

= AsciiDoc 基本記法
Author Name <author@example.com>
:toc: left
:icons: font
:source-highlighter: highlight.js

== 見出し

=== 小見出し

==== さらに小さい見出し

== テキスト装飾

*太字*, _イタリック_, `インラインコード`, [.line-through]#取り消し線#

== リスト

* 箇条書き 1
* 箇条書き 2
** ネスト

. 番号付き 1
. 番号付き 2

== アドモニション

NOTE: 注記の内容

TIP: ヒントの内容

WARNING: 警告の内容

IMPORTANT: 重要な内容

CAUTION: 注意の内容

== コードブロック

[source,python]
----
def hello():
    print("Hello, World!")
----

== テーブル

[cols="1,2,3"]
|===
| ヘッダー1 | ヘッダー2 | ヘッダー3

| セル1
| セル2
| セル3

| セル4
| セル5
| セル6
|===

== インクルード

include::chapter01.adoc[]

14.4 マークアップ言語の比較

| 特性 | Markdown | reStructuredText | AsciiDoc |
|------|----------|-----------------|----------|
| 学習コスト | 低い | 中程度 | 中程度 |
| 拡張性 | 低〜中（方言依存） | 高い | 高い |
| クロスリファレンス | 限定的 | 強力 | 強力 |
| テーブル | 基本的 | 柔軟 | 非常に柔軟 |
| アドモニション | 拡張必要 | 標準 | 標準 |
| PDF 出力 | ツール依存 | Sphinx 経由 | Asciidoctor |
| エコシステム | 最大 | Python中心 | Java/Ruby中心 |
| 採用事例 | GitHub, 多数 | Python公式 | Spring, Red Hat |

---

15. 国際化とローカライゼーション

15.1 国際化（i18n）対応の設計

国際化を考慮したドキュメントの設計:

1. ソーステキストの品質
   - 明確で簡潔な文章（翻訳しやすい）
   - 文化依存の表現を避ける
   - 慣用句やスラングを使わない
   - 例: ✗ "piece of cake" → ✓ "easy to complete"

2. ファイル構造
   docs/
   ├── en/                # 英語（ソース言語）
   │   ├── getting-started.md
   │   └── reference.md
   ├── ja/                # 日本語
   │   ├── getting-started.md
   │   └── reference.md
   └── zh/                # 中国語
       ├── getting-started.md
       └── reference.md

3. 翻訳不要な要素の分離
   - コード例
   - スクリーンショット（言語別に用意が必要な場合もある）
   - 数値、日付（ロケール対応）
   - 固有名詞のリスト

4. 翻訳管理ツール
   - Crowdin: Git 連携、自動翻訳
   - Transifex: 翻訳メモリ、用語集管理
   - Pontoon: Mozilla 開発のオープンソース
   - Weblate: Git ベースのオープンソース

15.2 日英翻訳のガイドライン

日本語→英語への翻訳で注意すべき点:

1. 主語の明示
   日本語: 「設定を変更します」（主語が省略）
   英語: "You change the settings." (主語を明示)

2. 曖昧な表現の具体化
   日本語: 「適切に設定してください」
   英語: "Set the timeout to 30 seconds."

3. 敬語表現の変換
   日本語: 「ご確認いただけますでしょうか」
   英語: "Please verify the settings."

4. 文の長さ
   日本語の1文は英語では2〜3文に分割することが多い

5. 用語の統一
   用語集（グロッサリー）を日英対応で管理
   
   | 日本語 | 英語 | 備考 |
   |--------|------|------|
   | 設定 | configuration / settings | 文脈により使い分け |
   | 実行 | execute / run | |
   | 認証 | authentication | |
   | 認可 | authorization | 認証と混同しない |
   | 展開 | deploy / deployment | |
   | 構築 | build | |

---

16. レビューと品質管理

16.1 ドキュメントレビューの種類

1. テクニカルレビュー
   レビュアー: エンジニア、SME（Subject Matter Expert）
   焦点: 技術的な正確性
   チェック項目:
   - コード例は正しいか
   - コマンドは動作するか
   - パラメータの説明は正確か
   - バージョン情報は最新か

2. エディトリアルレビュー
   レビュアー: テクニカルライター、エディター
   焦点: 文章の品質
   チェック項目:
   - スタイルガイドに準拠しているか
   - 一貫した用語を使用しているか
   - 文法・スペルに誤りはないか
   - 構造は論理的か

3. ユーザビリティレビュー
   レビュアー: 対象読者に近い人
   焦点: 実用性
   チェック項目:
   - 手順通りに作業を完了できるか
   - 不明点はないか
   - 情報は見つけやすいか
   - 前提知識は適切か

16.2 レビューチェックリスト

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

## 構造
- [ ] タイトルが内容を正確に反映している
- [ ] 見出しの階層が適切（H1 → H2 → H3 の順）
- [ ] 前提条件が明記されている
- [ ] 目次が正しくリンクされている

## 内容
- [ ] 技術的に正確である
- [ ] コード例がそのまま動作する
- [ ] バージョン情報が最新である
- [ ] エッジケースが記載されている
- [ ] エラーハンドリングの説明がある

## 文章
- [ ] 明確で簡潔な文章である
- [ ] 能動態を使用している
- [ ] 用語が統一されている
- [ ] スタイルガイドに準拠している
- [ ] 誤字脱字がない

## 書式
- [ ] コードブロックに言語が指定されている
- [ ] リンクが正しく動作する
- [ ] 画像に代替テキストがある
- [ ] テーブルのフォーマットが統一されている
- [ ] 注意書きが適切に使用されている

## アクセシビリティ
- [ ] 色だけに依存した情報伝達をしていない
- [ ] スクリーンリーダーで読める構造になっている
- [ ] 画像に代替テキストがある

16.3 自動チェックツール

リンティング・チェックツール:

| ツール | 用途 | 設定例 |
|--------|------|--------|
| markdownlint | Markdown 構文チェック | .markdownlint.json |
| Vale | 文体・スタイルチェック | .vale.ini |
| textlint | 日本語文章チェック | .textlintrc |
| alex | インクルーシブ言語チェック | .alexrc |
| write-good | 英語文章品質チェック | CLI |
| lychee | リンク切れチェック | CLI / CI |
| cspell | スペルチェック | cspell.json |

// .textlintrc（日本語テクニカルライティング用）
{
  "rules": {
    "preset-ja-technical-writing": {
      "sentence-length": { "max": 100 },
      "max-comma": { "max": 3 },
      "max-ten": { "max": 3 },
      "no-exclamation-question-mark": true,
      "no-doubled-joshi": true,
      "no-double-negative-ja": true,
      "no-mix-dearu-desumasu": {
        "preferInHeader": "である",
        "preferInBody": "ですます"
      },
      "ja-no-weak-phrase": true,
      "ja-no-redundant-expression": true,
      "no-unmatched-pair": true
    },
    "prh": {
      "rulePaths": ["prh-rules.yml"]
    }
  }
}

---

17. アクセシビリティ

17.1 Web アクセシビリティの基本

WCAG 2.1（Web Content Accessibility Guidelines）の原則:

1. 知覚可能（Perceivable）
   - テキストの代替手段を提供
   - 時間依存メディアの代替手段
   - 適応可能なコンテンツ
   - 識別可能なコンテンツ

2. 操作可能（Operable）
   - キーボードでアクセス可能
   - 十分な時間の提供
   - 発作の防止
   - ナビゲーション可能

3. 理解可能（Understandable）
   - 読みやすいテキスト
   - 予測可能な操作
   - 入力支援

4. 堅牢（Robust）
   - 互換性の確保

17.2 アクセシブルなドキュメントの書き方

## 見出し構造
- 見出しレベルを飛ばさない（H1 → H2 → H3）
- 見出しでセクションの内容が推測できるようにする

## 画像
- すべての画像に代替テキストを設定
  ✓ ![設定画面のスクリーンショット。「保存」ボタンが赤枠で強調されている](settings.png)
  ✗ ![スクリーンショット](settings.png)
  ✗ ![](settings.png)

- 装飾的な画像には空の alt を設定
  ![](decorative-divider.png)

## リンク
- リンクテキストは内容を説明する
  ✓ [インストール手順](install.md) を参照してください。
  ✗ インストール手順は [こちら](install.md)。
  ✗ 詳細は [ここ](install.md) をクリック。

## テーブル
- ヘッダー行を設定する
- 複雑なテーブルにはキャプション/説明を付ける
- セルの結合は避ける

## 色
- 色だけに依存した情報伝達をしない
  ✗ "赤いボタンをクリック"
  ✓ "「削除」ボタンをクリック"
- 十分なコントラスト比を確保（4.5:1以上）

---

18. SEO とディスカバラビリティ

18.1 テクニカルドキュメントの SEO

ドキュメントサイトの SEO 対策:

1. タイトルと見出し
   - ページタイトルに主要キーワードを含める
   - H1 はページに1つだけ
   - 見出しで内容が推測できるようにする
   - 「〜する方法」「〜ガイド」等の検索意図に合致する表現

2. メタデータ
   - description: ページの要約（120〜160文字）
   - og:title, og:description: SNS共有時の表示
   - canonical URL: 重複コンテンツの正規化

3. URL 設計
   ✓ /docs/getting-started/installation
   ✗ /docs/page?id=123
   ✗ /docs/2024/01/15/install

4. 内部リンク
   - 関連ページへの適切なリンク
   - パンくずリスト
   - サイトマップの提供

5. コンテンツ最適化
   - コード例を含む（コードスニペットはよく検索される）
   - エラーメッセージを本文に含める（エラー検索対策）
   - FAQ セクション（質問形式は検索に強い）

18.2 検索機能の実装

ドキュメントサイト内検索の選択肢:

1. Algolia DocSearch
   - 無料（オープンソースプロジェクト向け）
   - 高速なタイプアヘッド検索
   - 多くのドキュメントフレームワークと統合済み

2. Meilisearch
   - オープンソースの全文検索エンジン
   - セルフホスト可能
   - タイプミス耐性

3. ブラウザベース検索
   - lunr.js: クライアントサイド全文検索
   - Fuse.js: ファジー検索
   - MkDocs の search プラグイン

---

19. メトリクスと改善プロセス

19.1 ドキュメントのメトリクス

定量的メトリクス:

1. ページビュー / ユニークビジター
   - 各ページの閲覧数
   - セクション別のトラフィック分布

2. 検索メトリクス
   - サイト内検索クエリ（何が検索されているか）
   - 検索結果なし（コンテンツギャップの発見）
   - 検索後のクリック率

3. フィードバック
   - 「このページは役に立ちましたか？」の回答率
   - GitHub Issue / PR の数
   - サポートチケットの削減率

4. 完了率
   - チュートリアルの完了率
   - ページの離脱率（どこで読むのをやめたか）
   - 滞在時間

5. ドキュメントカバレッジ
   - API エンドポイントのドキュメント化率
   - 機能のドキュメント化率
   - コード例のカバレッジ

19.2 改善サイクル

ドキュメントの継続的改善プロセス:

1. 測定（Measure）
   - アナリティクスデータの収集
   - ユーザーフィードバックの収集
   - サポートチケットの分析

2. 分析（Analyze）
   - 最も閲覧されるページの特定
   - 離脱率の高いページの分析
   - 検索クエリの傾向分析
   - サポートで頻出する質問の特定

3. 優先順位付け（Prioritize）
   - インパクトの大きい改善を優先
   - コンテンツギャップの特定
   - 古い情報の更新計画

4. 実行（Execute）
   - コンテンツの作成・更新
   - 構造の改善
   - 検索最適化

5. 検証（Verify）
   - 改善後のメトリクス確認
   - ユーザーテストの実施
   - サポートチケット数の変化

---

20. チーム運営とワークフロー

20.1 テクニカルライティングチームの構成

役割と責任:

1. テクニカルライター
   - ドキュメントの企画、執筆、編集
   - スタイルガイドの策定と維持
   - ドキュメントツールの選定と管理
   - レビュープロセスの運営

2. 情報アーキテクト
   - ドキュメントサイトの構造設計
   - ナビゲーション設計
   - 分類体系（タクソノミー）の設計

3. エンジニア（コントリビューター）
   - コード例とAPIリファレンスの執筆
   - テクニカルレビュー
   - Docs as Code インフラの構築

4. プロダクトマネージャー
   - ドキュメントの優先順位決定
   - リリースに合わせたドキュメント計画
   - メトリクスの追跡

5. デザイナー
   - ドキュメントサイトのUI/UX
   - ダイアグラムやイラストの作成
   - ブランドガイドラインとの整合性

20.2 ドキュメント開発ワークフロー

ソフトウェアリリースとドキュメントの連動:

1. 計画フェーズ
   - 機能要件にドキュメント要件を含める
   - ドキュメントの優先度とスコープを決定
   - テンプレートの準備

2. 開発フェーズ
   - 機能開発と並行してドキュメントを作成
   - コードPRにドキュメント変更を含める
   - ドラフトのアーリーレビュー

3. レビューフェーズ
   - テクニカルレビュー（エンジニア）
   - エディトリアルレビュー（ライター）
   - ユーザビリティテスト（必要に応じて）

4. リリースフェーズ
   - 機能リリースと同時にドキュメントを公開
   - リリースノートの作成
   - 変更履歴の更新

5. メンテナンスフェーズ
   - フィードバックに基づく改善
   - 定期的な鮮度チェック
   - 非推奨情報の更新

20.3 コントリビューションガイド

# ドキュメントへのコントリビューション

## 始め方

1. リポジトリをフォーク
2. ブランチを作成: `git checkout -b docs/improve-auth-guide`
3. 変更を加える
4. ローカルでプレビュー: `mkdocs serve`
5. プルリクエストを作成

## 命名規則

- ブランチ名: `docs/<変更の説明>`
- コミットメッセージ: `docs: <変更内容>`
  例: `docs: add authentication troubleshooting section`

## スタイルガイド

- [スタイルガイド](./STYLE_GUIDE.md) に従ってください
- `npm run lint` で文章チェックを実行

## レビュープロセス

1. CI チェックが通ることを確認
2. テクニカルライターがレビュー
3. 必要に応じてエンジニアがテクニカルレビュー
4. 承認後にマージ

---

21. まとめ

21.1 テクニカルライティングのチェックリスト

ドキュメント作成前:
□ 読者を定義したか
□ ドキュメントタイプを決定したか（チュートリアル/ガイド/リファレンス/説明）
□ 情報の構造を設計したか
□ スタイルガイドを確認したか

ドキュメント作成中:
□ 一文一義で書いているか
□ 能動態を使用しているか
□ コード例は動作確認済みか
□ 前提条件を明記したか
□ 視覚的要素を適切に活用しているか

ドキュメント作成後:
□ テクニカルレビューを受けたか
□ エディトリアルレビューを受けたか
□ リンク切れがないか
□ スペルチェックを実行したか
□ アクセシビリティを確認したか

21.2 推奨リソース

書籍:
- 『技術者のためのテクニカルライティング入門講座』（髙橋慈子 著）
- "Docs for Developers" (Jared Bhatti et al.)
- "The Product is Docs" (Splunk Documentation Team)
- "Every Page is Page One" (Mark Baker)

オンラインリソース:
- Google Technical Writing Courses（無料）
  https://developers.google.com/tech-writing
- Write the Docs コミュニティ
  https://www.writethedocs.org/
- Diátaxis フレームワーク
  https://diataxis.fr/
- Google Developer Documentation Style Guide
  https://developers.google.com/style

ツール:
- regex101.com — 正規表現のテスト
- Vale — 文体チェッカー
- textlint — 日本語文章チェッカー
- Mermaid — ダイアグラム生成
- Excalidraw — 手書き風ダイアグラム

テクニカルライティングは、技術と言語の交差点に位置するスキルである。優れたドキュメントは、製品の価値を最大化し、開発者体験を向上させ、サポートコストを削減する。コードを書くように、ドキュメントも継続的に改善し、読者に最高の体験を提供し続けることが重要である。