READMEは説明書ではなく案内板

README.mdは、リポジトリを開いた人が最初に目にする文書です。GitHubはこのファイルをトップページに自動で表示します。

ここで全機能を説明しようとすると、かえって誰も読まなくなります。READMEが答えるべきなのは、次の3つだけです。

• これは何か
• どうやって動かすか
• 困ったらどこを見るか

最低限の構成

# プロジェクト名

一文で何かを説明する。

## 動かし方

1. 依存をインストールする
2. 環境変数を設定する
3. 起動する

## よくあるつまずき

- ポートが使用中のとき

冒頭の一文がいちばん重要

タイトルの直後の一文で、何をするものなのかが分からなければ、読み手はそこで離れます。「社内向けの勤怠管理システム」「求人と学習講座を扱うメディア」のように、名詞で言い切ってください。

手順はコピーできる形で

動かし方の手順は、そのまま貼り付けて実行できる形でコードブロックに入れます。「適宜読み替えてください」と書かれた手順は、読み替えられずに失敗します。

想定読者を1人決める

「明日このチームに入る人」を思い浮かべて書くと、分量が自然に決まります。その人が知らないことだけを書き、知っていることは省く。READMEが長くなるときは、たいてい読者を決めていません。

• READMEが答えるべき問い
• 最低限の構成
• 読み手を想定して書く