# テクニカルライティングガイドライン

効果的なテクニカルライティングの原則に基づいた、自然で読みやすい技術文書作成のためのガイドラインです。

## 基本原則：効果的なテクニカルライティングの「7つのC」

優れたテクニカルドキュメントは以下の品質を持ちます：

- **Clear（明確）**: 曖昧さがなく、容易に理解できる
- **Concise（簡潔）**: 必要な情報を最小限の言葉で表現
- **Correct（正確）**: 文法、事実、技術的内容に誤りがない
- **Coherent（一貫）**: 論理的に結びつき、スムーズに流れる
- **Concrete（具体的）**: 抽象的でなく、測定可能で明確
- **Complete（完全）**: 必要な情報がすべて含まれている
- **Courteous（丁寧）**: 読者を意識した適切なトーンと構成

## 1. 簡潔性の原則（Conciseness）

### 冗長表現の排除

#### 検出される表現とより良い代替案

| 検出される表現 | 推奨される表現 | 理由 |
|---------------|---------------|------|
| まず最初に | まず / 最初に | 意味の重複 |
| あらかじめ予測 | 予測 | 「予測」自体が事前の概念を含む |
| することができます | できます / します | 不必要な助動詞の重複 |
| する必要があります | してください / します | より直接的な表現 |
| 言うまでもなく | （削除） | 不要な前置き |

#### 改善例

```markdown
❌ まず最初に設定ファイルを開く必要があります。
✅ まず、設定ファイルを開きます。

❌ このAPIを使用することができます。
✅ このAPIを使用できます。
```

## 2. 明確性の原則（Clarity）

### 能動態の使用と具体的な動詞

#### 受動態から能動態への変更

| 受動的表現 | 能動的表現 | 改善効果 |
|-----------|-----------|---------|
| 処理が行われます | システムが処理します | 主語が明確 |
| データの変更を行う | データを変更する | 直接的な動作 |
| によって実行される | ○○が実行する | 行為者が明確 |

#### 改善例

```markdown
❌ データの検証が行われます。
✅ システムがデータを検証します。

❌ ファイルの変更を行ってください。
✅ ファイルを変更してください。
```

## 3. 具体性の原則（Concreteness）

### 抽象的表現の具体化

#### 曖昧な表現と具体的な代替案

| 抽象的表現 | 具体的表現の例 | 改善効果 |
|-----------|---------------|---------|
| 高速なパフォーマンス | 50ms未満の応答時間 | 測定可能な基準 |
| 大幅に向上 | 従来比200%向上 | 定量的な情報 |
| 効率的な | メモリ使用量を30%削減 | 具体的な効果 |
| 適切な | セキュリティ基準に準拠した | 明確な判断基準 |

#### 改善例

```markdown
❌ このAPIは高速なパフォーマンスを提供します。
✅ このAPIは50ms未満で応答します。

❌ 大幅にパフォーマンスが向上しました。
✅ 処理速度が従来比200%向上しました。
```

## 4. 一貫性の原則（Consistency）

### 用語と表現の統一

#### よくある不一致パターン

| 不一致の例 | 統一すべき表現 | 注意点 |
|-----------|---------------|--------|
| ユーザー/クライアント/顧客 | プロジェクトで統一 | 同一対象は同一用語 |
| 設定画面/設定ページ/環境設定 | UI名称で統一 | 機能名は正確に |
| です・ます調/だ・である調 | 文書全体で統一 | 文体の混在を避ける |

#### 改善例

```markdown
❌ ユーザーがログインし、クライアントが設定を変更します。
✅ ユーザーがログインし、ユーザーが設定を変更します。

❌ 設定画面を開き、設定ページで変更します。
✅ 設定画面を開き、設定画面で変更します。
```

## 5. 構造化の原則（Structure）

### 情報の論理的整理

#### 文の長さと構造

- **一文一義**: 一つの文には一つの主要なアイデアのみ
- **適切な長さ**: 50文字を超える文は分割を検討
- **論理的順序**: 時系列や重要度に基づいた情報配置

#### 改善例

```markdown
❌ この機能は複数のオプションを提供し、ユーザーが柔軟に設定でき、
   パフォーマンスも向上し、セキュリティも強化されています。

✅ この機能は複数のオプションを提供します。
   ユーザーは柔軟に設定できます。
   パフォーマンスが向上し、セキュリティも強化されています。
```

### リストと見出しの活用

- 連続する手順は番号付きリスト
- 関連項目は箇条書き
- 階層構造は見出しレベルで表現

## 実装での考慮事項

### ルールの適用レベル

このガイドラインは以下の優先順位で適用されます：

1. **正確性**: 技術的事実の正確性が最優先
2. **明確性**: 読者の理解を妨げない表現
3. **簡潔性**: 文書の目的に応じて調整
4. **丁寧さ**: 読者層に適したトーン

### カスタマイズ

プロジェクトの特性に応じて：

- 専門用語の定義と統一
- 読者層に応じた説明レベル
- 組織固有のスタイルガイド

## 参考資料

- [textlint](https://textlint.github.io/)
- [JTF日本語標準スタイルガイド](https://www.jtf.jp/tips/styleguide)
- [技術文書作成のベストプラクティス](https://developers.google.com/style)

---

このガイドラインは `ai-tech-writing-guideline` ルールの基準として使用されています。