Writing Technical Docs

テクニカルライティング

🎯 使用タイミング

• 技術文書作成時
• 報告書・レポート作成時
• ドキュメント・コメント記述時
• コードレビューコメント時

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

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

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

📖 詳細ガイド

PRINCIPLES.md

7つのC原則の詳細解説と実践例：

• 各原則の詳細説明
• Before/After の実例
• 実践的なガイドライン
• よくある間違いと改善例

STRUCTURE.md

文章・ドキュメント構造の原則：

• 文の長さと構造
• 一文一義の原則
• 能動態の使用
• README構造例
• コードコメントのベストプラクティス

REPORTS.md

報告書・レポートのフォーマット：

• 実装完了報告テンプレート
• 技術調査レポートテンプレート
• 進捗報告フォーマット
• 品質チェック項目

ANTI-PATTERNS.md

よくある誤りとチェックリスト：

• 冗長表現の排除
• 曖昧な表現の改善
• 技術用語の統一
• 文書作成チェックリスト

🚀 クイックスタート

技術文書を書く前に

1. 読者を特定: 誰が読むか、技術レベルは？
2. 目的を明確化: 何を伝えたいか、行動を促すか？
3. 7つのCを確認: PRINCIPLES.mdを参照

報告書を書く前に

1. フォーマット選択: REPORTS.mdからテンプレート選択
2. 必須項目確認: 各テンプレートの必須項目を確認
3. チェックリスト活用: ANTI-PATTERNS.mdで最終確認

💡 実践のポイント

優先順位

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

カスタマイズ

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

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

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

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

確認すべき場面

確認不要な場面

• 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 でチェック

⚡ よく使う表現の改善例

詳細は ANTI-PATTERNS.md を参照してください。