README の書き方について

最近、仕事で README を書いた。成果物を含むリポジトリは非公開だけれど、その際に参考になったチェックリストがあったので、備忘がてら内容について残す。

README についてこれまであまり意識したことはなかったけれど、現職では単独メンテナ状態のリポジトリがあるため、引き継ぎのことを考えて、README をしっかり書いておこうと思った。READMEをゼロから書く機会に恵まれている人もそうでない人もいると思うけれど、少なくとも自分が関わるリポジトリの README が読者にとって優しいものかどうかを評価する助けになるはず。もし足りないなと思ったら、PRを出してより良いREADMEにしていきたい。

また今回紹介する内容は、どちらかというと公開プロジェクトに対して適用できる部分が多いというのが正直なところ。とはいえ、非公開プロジェクトのREADMEについても十分価値があると感じたので、記事に残すことにした。

チェックリスト

今回参考にしたのは、こちらのリポジトリの内容。

github.com

職場で紹介してもらった Docs for Developers という本の巻末で、良いREADMEを書くための資料として紹介されていた。

There are many README checklists available, but Daniel Beck's is one of the best. *1

後述する作者の講演動画でも説明されているけれど、 README は以下4つの観点で読者が該当プロジェクトについて自信を持たせることができる：

Identify the project
Evaluate the project
Use the project
Engage with the project

この4つの観点が、上記チェックリストの見出し*2と対応している。

以下では、このチェックリストを大雑把に訳してみる。

プロジェクト識別の助けとして

ファイル名をつける
- README か README.extension とする
ファイルの最上部に、プロジェクトの名前を最初の見出しとして記載する
プロジェクト名の下にプロジェクトのURLを貼る
同じくプロジェクト名の下にプロジェクトのオーナーか作者を明記する

プロジェクト評価の助けとして

このプロジェクトについて説明する
- ○：何をするのか、あるいは達成するのか
- ×：何からできているのか
- What ではなく Why に焦点を当てること
このプロジェクトが想定するユーザは誰か、どのような条件で使われるべきものかを記述する

プロジェクト利用の助けとして

可能であれば、利用の前提条件を列挙する
インストールと初回利用の手順を列挙する
インストールと初回利用の手順が正しいことを確認する
- 手順通りにやってみて間違いなく動けばよし

プロジェクトについてより深く知るための助けとして

他のドキュメントがどこにあるのか読者に伝える
- 例えば：
  - Webサイト
  - ドキュメントファイル
  - Man ページ
  - ヘルプコマンド
  - README に付随する、在ルートディレクトリファイル： LICENSE, CONTRIBUTING, CODE_OF_CONDUCT, AUTHORS, CHANGELOG, そして BUGS
質問等の助けを求めることが可能な場所を読者に伝える
- メーリングリストやイシュートラッカー、フォーラムなど
プロジェクトに関して他者を助ける方法を読者に伝える
- オープンソースプロジェクトの場合は、プロジェクトへの貢献方法ガイドへのリンクを貼るなど