writing-documentation

ドキュメント作成スキル

Strunk & White の Elements of Style の原則を適用し、簡潔で明確な技術ドキュメントを作成します。

このスキルを使う場面

次の場合にこのスキルを使います：

• 新しいドキュメントを作成するとき（README、API ドキュメント、ガイド、チュートリアル、アーキテクチャドキュメント）
• 既存のドキュメントを改善するとき
• ドキュメントの品質をレビューするとき
• ユーザーが「もっと簡潔にして」や「明確にして」と依頼したとき
• ユーザーがドキュメント、docs、README、ガイド、チュートリアル、API ドキュメントについて言及したとき

次の場合はこのスキルを使わないでください：

• コードコメント（状況が異なるため、別のスキルが必要です）
• マーケティングコピー（中立的で明確な表現ではなく、説得力のある語調が必要です）
• 個人ブログの投稿（個人の語り口が必要です）

ワークフロー

ワークフロー 1：新しいドキュメントを作成する

手順：

1. 目的を理解する

   • このドキュメントの主な目的は何ですか？
   • 対象読者は誰ですか？
   • 読者は読んだあと、何を達成する必要がありますか？

2. 執筆の原則を確認する

   • reference/strunk-white-principles.md を読んで、基本原則を理解します

3. ドキュメントの種類を決める

   • reference/doc-types.md を読んで、適切な種類を選びます
   • ガイドラインに基づいて、必要なセクションを特定します

4. ドキュメントの下書きを作成する

   • 執筆中に Strunk & White の原則を適用します

5. 品質を検証する

   • 品質チェックリスト（以下）に従って確認します
   • 必要な情報がすべて含まれていることを確認します
   • ドキュメントが目的を達成していることを確認します

ワークフロー 2：既存のドキュメントを改善する

手順：

1. 現在のドキュメントを読む

   • その目的と対象読者を理解します
   • 具体的な問題（冗長さ、不明瞭なセクション、情報の不足）を記録します

2. 執筆の原則を確認する

   • reference/strunk-white-principles.md を読みます
   • 変更前と変更後のパターンについて、reference/examples.md を確認します

3. 改善を適用する

   • 不要な語句を削除します
   • 受動態を能動態に変えます
   • 曖昧な記述を明確にします
   • 重複をなくします
   • 必要に応じて構成を改善します

4. 改善内容を検証する

   • 品質チェックリストに従って確認します
   • 情報が失われていないことを確認します
   • 明確さが向上したことを確認します

ワークフロー 3：ドキュメントをレビューする

手順：

1. 執筆の原則を確認する

   • reference/strunk-white-principles.md を読みます
   • reference/doc-types.md にある関連ガイドラインを確認します

2. 品質基準に照らして評価する

   • 品質チェックリスト（以下）に従って確認します
   • 違反している項目を具体例とともに記録します

3. フィードバックを提供する

   • 見つかった問題を具体的に列挙します
   • 違反している原則を示します
   • 具体的な改善案を提案します

判断の枠組み

新規作成と改善の使い分け

次の場合は新しいドキュメントを作成します：

• ドキュメントが存在しない
• 既存のドキュメントに根本的な誤りがある、または古くなっている
• 大幅な再構成が必要である（書き直す方が効率的）

次の場合は既存のドキュメントを改善します：

• 基本的な構成と情報に問題がない
• 文体や明確さの問題を段階的に修正できる
• 特定のセクションを強化する必要がある

ドキュメントの種類を選ぶ

詳しいガイドラインについては、reference/doc-types.md を参照してください。簡単な一覧：

• README：プロジェクトの概要、クイックスタート、主な入口
• API ドキュメント：関数やエンドポイントのシグネチャと動作に関するリファレンス
• チュートリアル／ガイド：特定の目標を達成するための、段階的な学習手順
• アーキテクチャ／設計ドキュメント：システム構造、判断、トレードオフの説明
• CLI ツールドキュメント：オプションと例を含むコマンドリファレンス

簡潔さと網羅性の優先順位

次の場合は簡潔さを優先します：

• ドキュメントの種類がリファレンス（README、API ドキュメント、CLI ドキュメント）
• 読者がすばやく内容を確認する必要がある
• はじめに／クイックスタートのセクション

次の場合は網羅性を優先します：

• ドキュメントの種類が学習向け（チュートリアル、ガイド）
• 複雑な概念を詳しく説明する必要がある
• アーキテクチャの決定について、十分な根拠を示す必要がある

両方のバランスを取ります：

• 概要セクションは簡潔にし、詳細なサブセクションを設ける
• すべてを埋め込むのではなく、詳細な情報へのリンクを設定する
• 段階的に情報を開示するパターンを適用する

品質チェックリスト

内容

• 目的が明確である
• 必要な情報が含まれている
• 不要な情報がない
• 正確である

文章（基本原則）

• 能動態を中心に使っている
• 断定的に述べている（曖昧な表現を避けている）
• 肯定形を使っている
• 具体的で明確な言葉を使っている
• 簡潔である（無駄な言葉がない）

構成

• 論理的に構成されている
• 見出しが明確である
• 内容をすばやく確認できる
• 役立つ箇所に例がある

技術ドキュメント

• コード例を実行できる
• コマンドに必要なコンテキストがすべて含まれている
• 前提条件が明記されている
• エラーケースを網羅している

参照ファイル

各参照ファイルを読み込むタイミング

reference/strunk-white-principles.md を読み込む：

• ドキュメントの執筆・改善を始めるときは毎回
• ドキュメントをレビューするとき

reference/doc-types.md を読み込む：

• 執筆するドキュメントの種類を選ぶとき
• ドキュメントの種類ごとに必要なセクションが不明なとき
• ドキュメントの構成をレビューするとき

reference/examples.md を読み込む：

• 既存のドキュメントを改善するとき（パターンを参照）
• 具体的な修正前・修正後の例が必要なとき

よくある落とし穴

原則の読み込みを省略する：執筆前に必ず reference/strunk-white-principles.md を読み込んでください。

ガイドラインに厳密に従いすぎる：プロジェクト固有のニーズに合わせて調整してください。すべてのセクションが必要なプロジェクトもあれば、追加のセクションが必要なプロジェクトもあります。

編集しすぎる：「不要な言葉を省く」とは、価値を加えない言葉を削除することです。読者の目的に役立つ情報はすべて残してください。

簡潔さのために正確さを犠牲にする：常に正確さを優先してください。説明は簡潔にしつつ、誤解を招く表現は避けてください。

用語の不統一：概念ごとに用語を一つ選び、一貫して使用してください。

メモ

• このスキルは反復的に使用できます。同じドキュメントに何度適用しても品質は低下しません（冪等です）。
• 量より質が重要です。短く明快なドキュメントのほうが、網羅的でもわかりにくいドキュメントより優れています。