効果的な README の作成

概要

README はあなたの読者が持つ質問に答えます。異なるオーディエンスは異なる情報を必要とします。OSS プロジェクトへのコントリビューターは、config フォルダを開く将来のあなたとは異なるコンテキストが必要です。

常に問う:「誰がこれを読むのか、そして彼らは何を知る必要があるのか?」

プロセス

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

質問: 「どの README タスクに取り組んでいるか?」

タスク	いつ
作成	新しいプロジェクト、README がまだない
追加	何かを文書化する必要がある
更新	機能が変わった、コンテンツが古い
レビュー	README がまだ正確かどうかを確認

ステップ 2: タスク固有の質問

初期 README を作成する:

1. プロジェクトのタイプは? (下記の Project Types を参照)
2. このプロジェクトはどんな問題を一文で解決するのか?
3. 「動作している」状態への最速の道のりは?
4. ハイライトするべき注目すべきことはあるか?

セクションを追加する:

1. 何を文書化する必要があるか?
2. 既存の構造の中でどこに配置すべきか?
3. 誰がこの情報を最も必要としているか?

既存のコンテンツを更新する:

1. 何が変わったか?
2. 現在の README を読み、古いセクションを特定する
3. 具体的な編集を提案する

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

1. 現在の README を読む
2. 実際のプロジェクト状態と照らし合わせる (package.json、メインファイルなど)
3. 古いセクションにフラグを立てる
4. 存在する場合は「最後にレビュー」した日付を更新する

ステップ 3: 常に質問する

ドラフト作成後、質問してください:「見落とした可能性のあるハイライトまたは含めるべきことはあるか?」

プロジェクトタイプ

タイプ	オーディエンス	主要セクション	テンプレート
Open Source	コントリビューター、世界中のユーザー	Install、Usage、Contributing、License	templates/oss.md
Personal	将来のあなた、ポートフォリオ閲覧者	機能説明、Tech stack、学習内容	templates/personal.md
Internal	チームメイト、新入社員	Setup、Architecture、Runbooks	templates/internal.md
Config	将来のあなた (困惑している)	ここにあるもの、理由、拡張方法、注意点	templates/xdg-config.md

不明な場合はユーザーに聞く。すべてに OSS のデフォルトを仮定しないでください。

必須セクション (すべてのタイプ)

すべての README は最低限でも以下を必要とします:

1. Name - 自明なタイトル
2. Description - 1-2 文で「何」と「なぜ」
3. Usage - 使い方 (例があるとよい)

参照資料

• section-checklist.md - プロジェクトタイプ別に含めるべきセクション
• style-guide.md - 一般的な README の間違いと文体ガイダンス
• using-references.md - より詳しい参考資料ガイド