crafting-effective-readmes

効果的な README の書き方

概要

README は、読者が抱く疑問に答えるためのものです。読者によって必要な情報は異なります。OSS プロジェクトへのコントリビューターには、設定フォルダーを開く未来の自分とは異なる文脈が必要です。

常に確認すること: 誰が読むのか、そして読者は何を知る必要があるのか？

プロセス

ステップ 1: タスクを特定する

確認: 「今どの README のタスクに取り組んでいますか？」

タスク	対象となる場合
作成	新しいプロジェクトで、まだ README がない
追加	新しい内容を文書化する必要がある
更新	機能が変わり、内容が古くなっている
レビュー	README がまだ正確かどうかを確認する

ステップ 2: タスク別の質問

初期 README の作成:

1. どの種類のプロジェクトですか？（下記の「プロジェクトの種類」を参照）
2. このプロジェクトは、一文でどんな問題を解決しますか？
3. 「動いた」状態にするまでの最短経路は何ですか？
4. 特に強調しておきたいことはありますか？

セクションの追加:

1. 何を文書化する必要がありますか？
2. 既存の構成のどこに配置するのがよいですか？
3. 誰がこの情報を最も必要としていますか？

既存の内容の更新:

1. 何が変わりましたか？
2. 現在の README を読み、古くなっているセクションを特定します
3. 具体的な修正案を提示します

レビュー・リフレッシュ:

1. 現在の README を読みます
2. 実際のプロジェクトの状態（package.json、メインファイルなど）と照らし合わせます
3. 古くなっているセクションを指摘します
4. 「最終レビュー日」がある場合は、その日付を更新します

ステップ 3: 必ず確認する

下書きを作成した後、次のように確認します: 「ほかに強調したい点や、含めるべき内容で見落としているものはありませんか？」

プロジェクトの種類

種類	対象読者	主要なセクション	テンプレート
オープンソース	コントリビューター、世界中のユーザー	インストール、使い方、コントリビューション、ライセンス	templates/oss.md
個人	未来の自分、ポートフォリオの閲覧者	何をするものか、技術スタック、学び	templates/personal.md
社内	チームメンバー、新入社員	セットアップ、アーキテクチャ、運用手順書	templates/internal.md
設定	未来の自分（混乱している状態）	ここにあるもの、理由、拡張方法、注意点	templates/xdg-config.md

不明な場合はユーザーに確認してください。 すべてに OSS のデフォルトを前提としないでください。

必須セクション（全種類共通）

すべての README には、最低限次のものが必要です:

1. 名前 - 内容がひと目でわかるタイトル
2. 説明 - 何であり、なぜ必要かを 1〜2 文で
3. 使い方 - 利用方法（例があると役立ちます）

参考資料

• section-checklist.md - プロジェクトの種類別に含めるセクション
• style-guide.md - よくある README の間違いと文章の書き方
• using-references.md - より詳しい参考資料の使い方ガイド