# Writing Technical Docs

> Guides technical documentation and report writing. Applies the 7 Cs principle (Clear, Concise, Correct, Coherent, Concrete, Complete, Courteous). Use for writing technical documents, reports, and code comments. For academic writing (essays, papers, dissertations), use writing-academic-papers instead.

- Skill: `majiayu000/writing-technical-docs-2` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add majiayu000/writing-technical-docs-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/writing-technical-docs-2/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/writing-technical-docs-2

---


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

## 🎯 使用タイミング
- **技術文書作成時**
- **報告書・レポート作成時**
- **ドキュメント・コメント記述時**
- **コードレビューコメント時**

## 📋 7つのCの原則（概要）

効果的なテクニカルドキュメントは以下の品質を持ちます：

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

## 📖 詳細ガイド

### [PRINCIPLES.md](./references/PRINCIPLES.md)
7つのC原則の詳細解説と実践例：
- 各原則の詳細説明
- Before/After の実例
- 実践的なガイドライン
- よくある間違いと改善例

### [STRUCTURE.md](./references/STRUCTURE.md)
文章・ドキュメント構造の原則：
- 文の長さと構造
- 一文一義の原則
- 能動態の使用
- README構造例
- コードコメントのベストプラクティス

### [REPORTS.md](./references/REPORTS.md)
報告書・レポートのフォーマット：
- 実装完了報告テンプレート
- 技術調査レポートテンプレート
- 進捗報告フォーマット
- 品質チェック項目

### [ANTI-PATTERNS.md](./references/ANTI-PATTERNS.md)
よくある誤りとチェックリスト：
- 冗長表現の排除
- 曖昧な表現の改善
- 技術用語の統一
- 文書作成チェックリスト

## 🚀 クイックスタート

### 技術文書を書く前に
1. **読者を特定**: 誰が読むか、技術レベルは？
2. **目的を明確化**: 何を伝えたいか、行動を促すか？
3. **7つのCを確認**: [PRINCIPLES.md](./references/PRINCIPLES.md)を参照

### 報告書を書く前に
1. **フォーマット選択**: [REPORTS.md](./references/REPORTS.md)からテンプレート選択
2. **必須項目確認**: 各テンプレートの必須項目を確認
3. **チェックリスト活用**: [ANTI-PATTERNS.md](./references/ANTI-PATTERNS.md)で最終確認

## 💡 実践のポイント

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

### カスタマイズ
プロジェクトの特性に応じて：
- 専門用語の定義と統一
- 読者層に応じた説明レベル
- 組織固有のスタイルガイド

## ユーザー確認の原則（AskUserQuestion）

**判断分岐がある場合、推測で進めず必ずAskUserQuestionツールでユーザーに確認する。**

### 確認すべき場面

| 確認項目 | 例 |
|---|---|
| 対象読者 | 開発者, マネージャー, エンドユーザー |
| ドキュメント形式 | Markdown, PDF, HTML, Confluence |
| 詳細レベル | 概要のみ, 手順書, 詳細仕様書 |
| 言語 | 日本語, 英語, 両方 |
| テンプレート | ADR, RFC, 技術設計書, 運用手順書 |

### 確認不要な場面

- 7つのCの原則の適用（常に適用）
- Markdownの基本記法
- コードコメントの記述（コードの言語に従う）

## 🔗 関連スキル
- **writing-clean-code**: SOLID原則・コメントとドキュメントの品質
- **testing**: テストケース名の明確性
- **securing-code**: セキュリティドキュメント作成

## 📚 学習の流れ

```
1. 基本原則を理解
   └─ PRINCIPLES.md で7つのCを学ぶ

2. 構造化を実践
   └─ STRUCTURE.md で文章構造を学ぶ

3. テンプレート活用
   └─ REPORTS.md でフォーマットを選択

4. 品質確認
   └─ ANTI-PATTERNS.md でチェック
```

## ⚡ よく使う表現の改善例

| ❌ 避けるべき表現 | ✅ 推奨される表現 |
|---------------|---------------|
| まず最初に | まず / 最初に |
| することができます | できます / します |
| 高速なパフォーマンス | 50ms未満の応答時間 |
| データの処理が行われます | システムがデータを処理します |

詳細は [ANTI-PATTERNS.md](./references/ANTI-PATTERNS.md) を参照してください。