pragmatic-docs

実用的なドキュメント作成

読者の時間を尊重し、方法より先に理由を説明し、抽象的な説明ではなく実例を使い、独自の見解をためらわずに示すドキュメントを書きましょう。Philip Greenspun のアプローチに着想を得ています。まず大きなアイデアを示し、実際のコードを文脈の中で見せ、トレードオフを率直に認め、読者が読むのをやめる前に書くのをやめましょう。

基本原則

1. まず理由を示す

すべてのドキュメントは大きなアイデアから始めます。これは何か、なぜ存在するのか、どんな問題を解決するのかを、1～3 段落で説明します。なぜ読者が関心を持つべきかを 3 段落で説明できないなら、そのプロジェクトを十分に理解していません。

悪い例：「このモジュールは、柔軟で拡張可能なエンタープライズグレードのソリューションを提供します……」 良い例：「ユーザーはいつも同じ 5 つの質問をしていました。このツールはそれらに自動で回答するので、メンテナーは安心して眠れます。」

2. 抽象的な説明より例を

実際の例ひとつのほうが、説明 3 段落より多くを伝えます。実際のコマンド、実データ、本物の出力を示しましょう。具体的なシナリオを示せるなら、foo、bar、WidgetFactory、MyApp などを作り出してはいけません。

コードは説明の流れに織り込みましょう。「例」専用の隔離された場所に追いやってはいけません。データモデルを説明するときは、その場でスキーマを示しましょう。CLI を説明するときは、コマンドとその出力を本文に示しましょう。

3. 見解には価値がある

自分の考えを述べましょう。「この理由で、Y より X のほうが優れています」は、「X と Y のどちらも選択肢です」より役に立ちます。トレードオフを認め、推奨する方法を示し、その理由を説明しましょう。読者は異論を唱えるかもしれませんが、少なくとも評価する立場が示されています。

4. 制限について率直に伝える

うまく機能しないことがあれば、そう伝えましょう。特定の用途に適したツールがほかにあるなら、それを紹介しましょう。「日付順に表示したい場合は、/news モジュールのほうが適しています」と伝えるほうが、モジュールが何でもできるふりをするより親切です。

5. 簡潔さは敬意

README が 300 行を超えるなら、別のドキュメントに分けるべきです。定型的なセクションで水増ししてはいけません。すべての文に存在意義が必要です。空になるセクションや、ごく単純な 1 行だけのセクションは省きましょう。

---

ドキュメントの構成

状況に合わせてこの構成を調整してください。すべてのセクションがすべてのプロジェクトに当てはまるわけではありません。テンプレートを埋めるためだけに、空のセクションや内容の乏しいセクションを絶対に含めないでください。

大きなアイデア（必須）

必ず記載します。以下を 1～3 段落で説明します。

• これは何か？
• なぜ存在するのか？どんな問題を解決するのか？
• 誰のためのものか？

このセクションだけを読んでも、読み進めるかどうか判断できるように書きましょう。すぐに文脈を説明できない専門用語は使いません。「提供を目指します」ではなく、実際に何をするのかを明確に述べます。

## What is this?

PhotoResize watches a directory for new images and resizes them to three
standard sizes for web delivery. We built it because our CMS required
manual image processing and editors were wasting 20 minutes per article
on something a script handles in 2 seconds.

クイックスタート（該当する場合）

「これを見つけた」状態から「自分の環境で動作する」状態になるまでの、可能な限り短い手順です。コマンドは最大 10 行です。セットアップに本当にそれ以上必要な場合は、最短手順を示し、詳しいインストール手順へのリンクを載せます。

## Quick Start

pip install photoresize
photoresize watch ./uploads --output ./public/images

パッケージマネージャーがすでにユーザーに伝えている内容を繰り返してはいけません。すべてのフラグを列挙する必要もありません。動作する状態まで案内しましょう。

内部の仕組み（該当する場合）

内部でどのように動作するかを説明します。ただし、内部の仕組みを理解することが実際にユーザーの役に立つ場合に限ります。アーキテクチャの判断は仕様書のように列挙するのではなく、文章で説明します。データモデルは UML 図やフィールドの文章説明ではなく、実際のスキーマや型定義で示します。

Greenspun のパターンに従いましょう。まずデータモデルを示し、次に興味深い判断について説明します。どのような制約を加え、その理由は何か？何を保存しないことにし、その理由は何か？

## Under the Hood

The core data model is simple — one table per feed source, one table
for processed items:

    create table feed_sources (
        source_id   serial primary key,
        url         text not null unique,
        check_interval_minutes  integer default 60
    );

We chose not to store the full article body because it doubles storage
without clear benefit — the original URL is always one click away.

設定／API（該当する場合）

型、シグネチャ、--help の出力から明らかではないことだけを記載します。以下に重点を置きます。

• 一見わかりにくいデフォルト値と、その選択理由
• 組み合わせると意外な動作をするオプション
• 90％のユーザーが変更する必要のある唯一の設定キー

型システム全体や CLI の --help を Markdown で再現してはいけません。そのために --help があります。

例（推奨）

抽象的なデモではなく、実際のシナリオを紹介します。それぞれの例は、実際に誰かが抱えている問題を解決するものにしてください。各例の冒頭に、このパターンを「いつ」使うのかを説明する一文を添えてください。

### Resizing for social media cards

Social platforms crop unpredictably. Force a 2:1 aspect ratio and let
the smart-crop algorithm pick the focal point:

    photoresize convert photo.jpg --aspect 2:1 --smart-crop --output card.jpg

関連プロジェクト／モジュール（該当する場合）

代替ツールや補完的なツールへの相互参照を記載します。それぞれについて、読者が「いつ」代わりに使うべきかを一文で説明してください。競合製品の一覧ではなく、誠実な指針を示すものです。

## Related

- **ImageMagick** — better if you need arbitrary image transformations
  beyond resizing. We actually shell out to it under the hood.
- **sharp** — faster for Node.js projects; PhotoResize is for Python
  shops that want a CLI-first workflow.

制限事項／今後の予定（任意）

ユーザーが直面する、実際にある、気づきにくい制限事項がある場合に限り記載してください。実装するかどうかも分からない機能のロードマップは含めないでください。

## Limitations

- No WebP output yet (tracking in #142)
- Smart cropping works poorly on images with multiple faces

---

執筆ルール

文体とトーン

• 能動態を使います。「サーバーが応答を送信します」と書き、「応答がサーバーによって送信されます」とは書きません。
• 設計の理由を共有する場合は、一人称を使ってもかまいません。「理由があって X を選びました」や「これを作ったきっかけは……」のように書きます。
• ある有能なエンジニアが別のエンジニアに説明するように書きます。マーケティングチームや法務部門のような文体にはしません。
• 自然に出てくるユーモアや個性は歓迎します。無理にひねり出さないでください。

含める内容

• 決定事項だけでなく、決定した「理由」。
• 実際のコマンド、実際のデータ、実際の出力。
• トレードオフ — 何を諦め、何を得たのか。
• 他のドキュメントの内容を埋め込まず、リンクによる相互参照。
• 各コードブロックの前に、そのコードを説明する一文。

省く内容

• 本当に役立つもの（ビルド状況、バージョン、ライセンス）以外のバッジ。多くても 2～3 個にします。
• 100 行未満のドキュメントの目次。
• --help、型シグネチャ、JSDoc で確認できる情報を繰り返すセクション。
• 「目指す」「活用する」「利用する」「促進する」「エンタープライズグレード」という言葉。
• README に埋め込んだ自動生成の API ドキュメント。代わりにリンクしてください。
• 内容のない空のテンプレートセクション（「## Contributing」「## License」など）。

ドキュメント内のコード

• 説明文の中にコードを示し、説明する文の直後に置きます。
• コードブロックには、疑似コードではなく、プロジェクトで実際に使っている言語を使います。
• スニペットは短く保ちます。理想は 5～15 行です。長くなる場合は、一度に見せる量が多すぎます。
• 注目すべき行にはコメントを付けます。当たり前のことにはコメントを付けません。

長さの目安

ドキュメント	目標の長さ	備考
README.md	50～200 行	最初に目にするドキュメントです。簡潔にまとめ、詳細はリンクで案内します。
モジュールドキュメント	30～150 行	1 モジュール = 1 つの役割 = 1 つのドキュメントです。
CONTRIBUTING.md	30～80 行	セットアップ + 規約 + PR の手順。それ以上は不要です。
アーキテクチャドキュメント	100～300 行	核となる考え方 + データモデル + 重要な決定事項。

ドキュメントが目標の長さを超える場合は、削るのではなく分割を検討してください。焦点を絞った 2 つのドキュメントのほうが、長大な 1 つのドキュメントより優れています。

---

避けるべきアンチパターン

テンプレートの墓場。 15 個のセクションがあり、その半分が「TODO」または一文だけの README。すべてのセクションに存在する価値が必要です。

API の写し鏡。 コードを見れば分かる関数シグネチャやパラメーターの型を、すべて再掲するドキュメント。シグネチャではなく、動作、決定事項、注意点を説明してください。

企業的な文体。 「このプロジェクトは、包括的でスケーラブルなソリューションの提供を目指しています……」——こんな言い方をする人はいません。何をするものなのかを伝えてください。

完全性の罠。 あらゆる例外ケースやオプションを最初からすべて記録しようとすること。大半の人が使う方法をしっかり説明し、例外ケースはイシューやディスカッションで扱いましょう。

変更履歴 README。 変更履歴が大半を占める README。変更履歴には CHANGELOG.md と git log を使ってください。

バッジの壁。 README の冒頭にバッジが 12 個並び、その半分が壊れている状態。本当に役立つもの（CI の状況、npm のバージョン、ライセンス）を 2～3 個選びましょう。

---

このスキルを適用する場面

次のような場合に、このアプローチを使用します。

• あらゆるソフトウェアプロジェクトの新しい README.md を作成する
• 既存のドキュメントを改善または書き直す
• docs/ ディレクトリにモジュールレベルのドキュメントを作成する
• CONTRIBUTING.md、アーキテクチャドキュメント、セットアップガイドを作成する
• 新しい機能、API、サービスについて記述する
• ドキュメントが簡潔で役立つものになっているかレビューする

プロジェクトの種類に応じた調整

ライブラリ／パッケージ： 最初にクイックスタート（インストール＋基本的な使い方）を示します。「基本となる考え方」では、代替手段ではなくこのライブラリを選ぶべき場面を説明します。

CLI： 最もよく使われるコマンドを最初に示します。実際のターミナル出力を掲載します。--help を見ただけでは分かりにくいフラグについて説明します。

API／サービス： 最初に「基本となる考え方」（このサービスが何をするものか）を示します。実際のリクエストとレスポンスの組み合わせを掲載します。データモデルは「内部の仕組み」で説明します。

フレームワーク： 最初に「基本となる考え方」（このフレームワークの基本理念）を示します。クイックスタートでは「Hello World」まで進めます。「内部の仕組み」ではメンタルモデルを説明します。

社内ツール： 制限について、より率直に説明します。読者は競合製品に乗り換えられないため、既知の問題を回避できるよう支援します。