technical-writing

技術文書：まず流し読みされ、最後まで読んでもらえるだけの信頼を得る

開発者は、取り組むと決める前に文書を流し読みします。文書が最初の画面で次の3つの質問に答えれば、じっくり読んでもらえます。これは何か、なぜ気にかけるべきか、どう始めればよいか。以下のすべては、この約束を果たすためのものです。

リソース	次の場合に読みます…
resources/doc-types.md	どの種類のページを書くかを選ぶ場合 — Diátaxis の4つのモード、チュートリアルとハウツーの違い、モデルが扱わない種類、種類ごとに適用する最小限主義
resources/readme.md	README を書く、または全面的に見直す場合 — 認知のファネル、短い版と長い版の決着、README 主導の開発
resources/docs-quality.md	文書を検証可能にする場合 — 文章のリント、実行可能な例、リンクの確認、摩擦ログ、時代に左右されない文書、すべてのページを最初のページとして扱う考え方
resources/agent-docs.md	AI エージェント向けの文書を作る場合 — llms.txt の率直な評価、Markdown エンドポイント、RAG で分割しやすいページ
resources/formatting.md	構成上のルールを確認する場合 — タイトル、見出し、段落、リスト、導入部と結び、目次
resources/references.md	上記のすべての主張の出典を確認する場合

ページごとに読者の主な目的を1つにする

ページの主な読者の目的を選びます。チュートリアル、ハウツー、リファレンス、または解説です（Diátaxis。率直に言って、その限界については resources/doc-types.md を参照してください）。同じ目的に役立つなら、補足資料が別の種類にまたがってもかまいません。目的が混在して次のアクション、網羅性の約束、または対象読者が不明確になる場合は、ページを分けます。

原則

• 読者を第一に — 得られる価値から始めます。構成の軸はシステムの内部構造ではなく、読者が次に取るアクションです。コードの作り方ではなく、読者に伝わる名前を付けます。
• 流し読みしやすく — セクションの価値を要約する明確な見出し、短い段落、意図的な強調を使います。流し読みする人に役立つ目印になるなら見出しを追加し、語数のノルマに合わせることはしません。
• 平易で直接的に — 能動態を使い、手順では二人称で呼びかけ、複雑な考えは短い文で説明します。断片や矢印を連ねるより、完全な文を使います。簡潔さより読みやすさが大切です。
• 選び抜き、圧縮しない — 文書を短く保つには、読者の次のステップに影響しない内容を削ります。読者が読み解かなければならない専門用語に文章を圧縮してはいけません。

重要な主張には裏付けが必要です

重要な機能、現状、互換性、定量的な主張は検証可能にします。説明文、判断であることを明示した内容、規範的な設計の根拠に、見せかけのコマンドや日付は必要ありません。一方、裏付けのない宣伝文句には必要です。

• 根拠なしに機能を主張しない：読者が検証できる数値、実行できるコマンド、開けるファイルを示します。「高速」は宣伝文句ですが、「このリポジトリの CI ではゲートの実行に14秒かかります」は裏付けのある主張です。
• 数値やバージョンは古くなる：文章中で引用する、変わりうる運用上の数値（テスト数、カバレッジ、バージョン）は保守の負担になります。自動生成するか、日付を付けるか、最新状態を保つルールに組み込みます（更新をすべての変更の完了条件に含めます）。
• 正直な制限も内容の一部であり、告白ではありません：ページの範囲から、実際には提供していない保護、カバレッジ、機能があると誤解されるおそれがある場合、読者が判断する箇所で制限を明示します。範囲がすでに明確な短い文書に、形式だけの制限事項セクションを追加する必要はありません。
• 待機状態や空の状態にも説明を付ける：「処理済みアイテム0件」が成功のように見えるのは、レイアウトによる嘘です。文書や例の出力箇所では、「処理するものがなかった」と「何もしなかった」を区別します。
• 長く使える、保守されるガイダンス：長く使う README やリファレンス文書では、担当者が決まっていない「近日公開」「現在」「新機能…」といった表現を避けます。リリースノート、移行ガイド、非推奨の通知、期間を限定したステータスページでは、時点を示す表現が必要なことがあります。その場合は、バージョンまたは日付と、担当者または削除条件を併記し、古びた宣伝文句ではなく根拠として残るようにします。

ドキュメントは振る舞いを記述します — 検証しましょう

システムを説明するドキュメントは、そのシステムについての主張であり、 主張は検証されるものです。

• 記憶ではなくソースと照らして検証する：ドキュメントで読者が頼りにするよう求める重要なフラグ、終了コード、 設定キー、実行コマンドはすべて、公開前にコードと照合します。安全で、許可されており、妥当な範囲であれば主張を実行して確認し、 そうでない場合は根拠の不足を記録します。
• 機械で確認できることは機械で確認する：目次のアンカーはレンダラーの実際のスラッグ規則と照合し、 リンクはファイルと、コマンド例はバイナリと照合します。手作業での確認は最後の手段であり、標準の方法ではありません。
• ドキュメントも同じくレビュー可能な変更で更新する：動作を変更したのにドキュメントを古いままにするのは、作業として未完了です。 全体に一律の方針を押し付けず、リポジトリのコミットポリシーに従います。

維持されるドキュメントには現在の事実を記載する

状態に基づくライフサイクルと Git の履歴調査ワークフローの全容については、resources/docs-quality.md を参照してください。

• 計画や仕様の作業スペースは、その成果が未完了の間だけ維持します。成果がリリースされたとき、または前提が覆されたときに削除します。アーカイブは Git の履歴が担います。
• 長く維持すべき制約は、現在の管理者に引き継ぎます。動作についてはソースまたは実行可能なテスト、アーキテクチャ上の決定については承認済み ADR、維持される手順についてはパッケージまたは運用ドキュメント、ドメイン用語については正式な用語集が該当します。
• 維持されるドキュメントを、削除済みの仕様や説明のないデリバリー識別子に依存させないでください。本当に必要な場合は、課題、PR、タスク、要件、仕様、ADR の識別子を示す前に、その目的を平易な言葉で説明します。
• ドキュメントのインデックスには分かりやすい起点を設け、現在の正式な情報、進行中の作業、決定事項、過去の根拠を区別します。信頼できるページを少数に絞り、見つけやすくすることを優先します。重複したもの、古くなったもの、推測に基づくもの、自動生成されたもの、管理者のいない文章は削除します。
• ドキュメントのみの変更で、TDD が必ず必要になるわけではありません。ただし、実行可能なドキュメント検証機能には、それが失敗することを証明する専用のテストが必要です。

AI エージェントにも伝わるように書く

開発者向けドキュメントの対象読者は、今や二者です。エージェントにも読み取れるドキュメントには、次の特徴があります。

• 文章だけに頼らず、一覧にする：エージェントが選択する必要のあるもの — オプション、フラグ、終了コード、 状態 — は、段落内だけでなく表の行にも記載します。
• 操作ごとに事前条件と事後条件を示す：実行前に満たすべき条件、実行後に変わること、終了コードの意味を説明します。 「状態 X では、次に取るべき正しいアクションは Y」のような状態遷移表は、どちらの読者にも物語形式の説明より有効です。
• 正確な文字列を示す：エージェントも、人間も切迫した状況ではコピー＆ペーストします。 正確なコマンド、設定ブロック、エラーメッセージを示し、言い換えは避けます。

ドキュメントの形式

• README／ランディングページ：最初の画面で、何か、なぜ使うのか、どう始めるのかに答えます。 ナビゲーションが実質的に改善される場合は目次を付けます。クイックスタートは正しい順序で一貫した手順にし、 クレジットの前に制限事項を正直に記載します。
• チュートリアル：冒頭でゴールを示します（「X が動作する状態にします」）。 手順に番号を付け、各手順の出力を示して、読者が順調に進んでいるか確認できるようにします。最後に次のステップを案内します。
• リファレンス：物語形式の説明より網羅性を優先します。フラグ、オプション、状態ごとに項目を設け、 可能であれば自動生成し、エージェントが読み取れる表にします。
• 提案書／設計書：求める決定事項を冒頭に示し、選択肢ごとの正直なトレードオフ、理由を添えた推奨案、 推奨を変える根拠となる情報を記載します。
• PR の説明／リリースノート：変更のコミットログ的な言い換えではなく、変更を読む人にとって何が変わるか （動作、移行）を説明します。

境界

状況	スキル
図の選定と作成	diagrams
REST/API リファレンスのセマンティクス（エラー、ページネーション、バージョニング）	api-design
CLI のヘルプテキスト、終了コード、出力設計	cli-design
期待事項、落とし穴、決定事項を新鮮なうちに文書化する	expectations
文章で使うドメイン用語	ubiquitous-language（インストールされている場合）
文単位の文体、一般的な文章、または AI らしい文章	clarity（インストールされている場合）
平易な英語、一般読者、翻訳、または ASD-STE100	simple-english（インストールされている場合）

検証チェックリスト

• 最初の画面で、何か／なぜか／始め方に答えている
• 見出しで得られる効果を要約している。必要に応じて目次があり、そのアンカーは機械的に検証されている
• 重要な機能・現状・定量的な主張には根拠または日付が添えられ、宣伝文句には裏付けがある
• 読者が頼りにするコマンド、フラグ、実行可能な例は、ソースと照合して検証され、可能であれば実行されている
• 暗黙の適用範囲によって誤解を招くおそれがある場合、重要な制限が示されている
• 列挙可能な事実は表にまとめられ、コピーして使えるものには正確な文字列が示されている
• 数やバージョンは、最新状態を保つためのルールに沿って管理されるか、自動生成されている
• ドキュメントの変更は、説明対象の動作と同じレビュー可能な変更に含まれている
• 維持管理されているドキュメントには現状が記載され、完了または置き換え済みの作業スペースは削除されている
• 長期にわたる制約は、過去の成果物だけでなく、現在の担当者のもとで管理されている
• インデックスでは、現行の正式情報、進行中の作業、決定事項、履歴が区別されている