readme-best-practices

README のベストプラクティス

このスキルでは、API リファレンスではなくランディングページのように読める README の書き方を扱います。読者が読み続けるかどうかを決めるのは 3～5 秒以内なので、最初に表示される画面で続きを読みたいと思わせる必要があります。

README 作成のワークフロー

1. 一文の要約を書く — プロジェクトの機能と、なぜそれが重要なのかを具体的かつ力強い一文で述べます。「～するツールです」のような表現は避け、要点を印象的に伝えます。
2. 動作するコード例を最初に書く — インストール手順より前の、本文の最初の 5～10 行以内にコピーして実行できる例を配置します。価値をすぐに伝えます。
3. バッジを追加する — プロジェクトで CI や公開の仕組みを設定している場合は、タイトルの直下にビルド状況、バージョン、ライセンス、カバレッジのバッジを配置します。
4. クイックスタートを書く — プレースホルダーを読者が頭の中で置き換える必要がない形で、30 秒以内に実行できるようにします。
5. 補足セクションを追加する — 以下の構成を使って、機能、使い方、設定、コントリビューション、ライセンスを記載します。ただし、実際に役立つ情報があるセクションだけを含めます。
6. すべてのアセットとリンクを確認する — 参照している画像（スクリーンショット、demo.gif など）がディスク上に存在すること、公開前に内部リンクが正しく機能することを確認します。
7. 初見のつもりで読む — 初めてプロジェクトを見るつもりで最初の画面を読み返し、読み続けるかやめるかの判断に役立たない内容は削ります。

冒頭のフック

• プロジェクトの機能と、なぜそれが重要なのかを伝える、力強い一文から始めます。「～するツールです」のような表現ではなく、要点を印象的に伝えます。
• 動作するコード例を最初の 5 行以内に配置します。インストール方法を説明する前に、価値をすぐに伝えます。
• 「現代の目まぐるしく変化する世界では……」のような、前置きにすぎない表現で始めないでください。
• 「コーディングを楽しんで！」のような、中身のない締めくくりは避けてください。
• AI マーケティングでよく使われる「シームレス」「堅牢」「包括的」「最先端」「強力」「手間いらず」といった言葉は避けます。印象的に聞こえるかではなく、何をするのかを述べます。

標準的な構成

一般的な README では、以下のセクションをおおむねこの順序で含めると効果的です。プロジェクトに実際の情報を加えるものだけを含めます。

1. タイトル＋一文の要約 — プロジェクト名と、力強いフックとなる一文。
2. バッジ — ビルド状況、最新バージョン、ライセンス、テストカバレッジ。
3. クイックデモ — 動作を示すコードスニペット、GIF、またはスクリーンショット。
4. 機能 — 箇条書きを並べるのではなく、2 列の表にします（下記参照）。
5. インストール — 複数のパッケージマネージャーがある場合は、それぞれの正確なインストールコマンド。
6. クイックスタート／使い方 — コピーして実行できる最小限の例と、それに続く、少し高度な例をいくつか。
7. 設定 — オプション、環境変数、設定ファイルの形式。デフォルト値も記載します。
8. API リファレンス（またはそのリンク）— 公開 API が複雑なライブラリ向け。
9. FAQ／トラブルシューティング — issue で実際によく寄せられる 3～5 個の質問。
10. コントリビューション — 開発環境の設定方法、テストの実行方法、PR の提出方法。CONTRIBUTING.md がある場合はリンクします。
11. ライセンス — ライセンス名とライセンスファイルへのリンク。
12. 作者／謝辞 — メンテナーと主要な依存関係への謝意。

機能の見せ方

• **機能:** の形式で箇条書きを並べるのではなく、機能と説明の 2 列からなる機能表を使います。太字の見出しが繰り返される箇条書きより、表のほうがすばやく内容を把握できます。

| Feature | Description |
|---|---|
| Zero-config | Works out of the box with sensible defaults |
| Streaming | Handles gigabyte-scale files without loading them into memory |
| Type-safe | Full TypeScript definitions, no `any` in the public API |

クイックスタートの要件

• コピーしてそのまま実行できる内容にします。30 秒以内に実行できるようにします。
• シェルコマンドの先頭に $ を付けないでください。コピー＆ペーストの妨げになります。
• インストールコマンドと最小限の使い方の例を離れたセクションに分けず、まとめて示します。

npm install awesome-lib

awesome-lib run --input data.csv --output report.json

import { parse } from "awesome-lib";

const result = parse("data.csv");
console.log(result.summary);

文章と書式

• 文の長さや構成に変化をつけます。短い一文だけの項目、短い段落、表を織り交ぜてください。同じ長さの箇条書きが続くと、水増しのように感じられます。
• 見出しを使って、読者が必要なセクションにすぐ移動できるようにします。順番に読むことを強制しないでください。
• 動作を文章で説明する方法と実行可能な例を示す方法の両方がある場合は、実行可能な例を優先します。
• 行単位の書式を統一します。言語／コマンドごとにフェンス付きコードブロックを1つ使い、シンタックスハイライトのために言語タグ（```bash、```json）を明示します。

バッジ

• CI の状態、公開済みのバージョン、ライセンス、ダウンロード数、カバレッジなど、客観的で機械的に確認できる情報にバッジを使います。
• バッジの行は短く保ちます。バッジが3〜6個を超えると、箇条書きが延々と続くのと同じように煩雑になります。
• 一般的な情報源：カスタムバッジには shields.io、CI プロバイダー独自のバッジの Markdown、npm／PyPI の公式バッジスニペット。

アセットとリンク

• 画像リンクを追加する前に、参照するアセット（demo.gif、スクリーンショット）が実際にディスク上に存在することを確認します。最初の画面に壊れた画像があると、すぐに信頼を損ないます。
• 内部アンカーリンク（目次、「下の「設定」を参照」など）が実際の見出しに対応していることを確認します。
• リポジトリ内のアセットには相対パスを優先します。そうすれば、Git ホストでもパッケージレジストリでも正しく表示されます。

作成者／連絡先セクション

• 「Made by username」のようなテキストだけで済ませず、作成者／メンテナーを視覚的に示すカードやバッジを含めます。GitHub プロフィールバッジ、小さなアバターとリンク、スポンサー用ボタンなどを使うと、意図がより明確に伝わります。
• 複数のメンテナーがいるプロジェクトでは、名前だけを列挙するのではなく、担当する役割や領域とともにメンテナーを記載します。

避けるべきよくある間違い

• 価値を伝える前にインストール方法から説明すること。読者は、なぜインストールすべきなのかまだわかりません。
• 表にまとめる代わりに、設定オプションをすべて文章で説明すること。
• README の内容が実際の CLI／API と食い違うこと。実行できなくなった古い例は、例がないよりも有害です。
• 「驚異的な速さ」「エンタープライズグレード」といったマーケティング用語を技術文書に混在させること。文体を一つに決め、技術的な表現を保ちます。
• TypeDoc、Sphinx、godoc などの自動生成リファレンスがすでにあるのに、README に API ドキュメント全体を重複して記載すること。代わりに、そのリファレンスへリンクします。