この記事は、Rowan Manning氏による「Writing a Friendly README」(2016/3/14)を翻訳したものです。
あなたのプロジェクトのREADMEは、かなり重要です。そこはプロジェクトに初めて来た人が大抵最初に見るであろう場所であり、唯一のドキュメントであることもよくあります。あなたのオープンソースプロジェクトにとってのREADMEは、企業にとってのウェブサイトのようなものです。ウェブサイトはユーザーエクスペリエンスの注目を集めるところですが、READMEがユーザー観点で考えられることはほとんどありません。
この記事では、分かりやすいREADMEを書くために役立ち、開発者(ユーザー)の要求に見合い、開発者がプロジェクトを初めて見たのかよく知っているのかにかかわらず、またベテラン開発者なのか初心者なのかにも関係ない方法を提示します。
ここでは項目ごとに、「Paddington」という仮のプロジェクトを例に使って説明していきます。それでは一番上から始めましょう。
プロジェクトの見出し(Project Heading)
「1画面」(the fold)のあり方には議論の余地がありますが、ウェブサイトの一番上の部分は重要な情報を表示するのに使われるべきだというのは、広く認められています。同じ原則をREADMEにも当てはめられます。
では、一番重要なのは何でしょうか？プロジェクト名はとても重要で、何をするかを表します。そこで、追加してしまいましょう。
この部分は多くは新しいユーザー向けですが、READMEの一番上の部分は同じく既存ユーザーにも意味のあるものでもあるべきです。簡単に答えられる質問があります。既によく知っているプロジェクトを見に来るとき、以下のことを知りたくて来ます。
- 最新のバージョンはどれ？
- ビルドが通っているか？
新しいユーザーとしてなら、同じく簡単に答えられる質問は
- どんな言語で書かれているか？
- どの言語バージョンでサポートされているか？
- テストされているか？
- ライセンスはどうなっているのか？
これらの質問には、バッジで答えられます！
プロジェクトの説明のすぐ下にバッジを並べることにしました。1行ならそんなに多くのスペースを取りませんし、大量の情報を伝えられます。
きれいじゃありませんか？一貫性のあるバッジの画像とライセンス情報などのカスタムバッジなどを提供しているshields.ioというサービスを使っています。
プロジェクトやライブラリがそれが可能なぐらいシンプルである前提ですが、見出しの最後として使い方の例を入れることもできます。これは新しいユーザーが何をしているプロジェクトなのかを理解するのに大きな手助けをしますし、説明と同じぐらい役立つでしょう。
比較的小さなスペースで、一番上の部分にたくさんの情報を入れられました。やりましたね！次は、ユーザから来るもう少し付加的な疑問に答える必要があります。READMEは長く、そして情報を見つけるのが難しくなってしまう可能性があるので、ここでやるべき分別のあることと言えば、目次を追加することです。
目次(Table of Contents)
短いREADMEなんかより目次は役に立ちます。情報を探す辛さを和らげ、ドキュメント内の別の場所への便利なリンクをユーザーに提供します。
ユーザーが単に使い方を確認したいだけなのに、最初の1度しか役に立たない可能性のあるインストール方法までスクロールしなければならないなんてことがあるでしょうか？
必要条件(Requirements)
他の誰よりも新しいユーザーにより役立つ部分についに入ってきました。本当に読みやすく、そしてほしい情報を手に入れてもらえるようにしましょう。ここでは、あなたのプロジェクトで必要な条件の全てを書くところです。言語、言語のバージョン、パッケージマネージャー、OS。プロジェクトの実際のインストールする節で扱われないもの全てを書きます。
とても明確になるように、通常の文あるいは箇条書きで書けばよいでしょう。これは、自分のためにもなります。つまり、プロジェクトを実行できないのはなぜかという問い合わせのイシューが減らせます。
必要条件を書く際には、前提となる知識が必要なくてよいように書くべきです。言語やパッケージマネージャーへの必要なリンクを追加し、完全な新人さんを助けてあげましょう。
使い方(Usage)
使い方のドキュメントはおそらくREADMEの中で最も重要です。これがなければ、ほとんどの人はまともに動くまでコードを探検してみようとはしないでしょう。
READMEを書こうとしているプロジェクトの種類によりますが、この節はいろいろな書き方があります。プログラマティックなAPI、Webインターフェース、Web API、コマンドラインツール、そういったものに対するドキュメントが必要になるはずです。下のガイドラインはJavaScript APIに関するものですが、その他のインターフェースにも同じく適用できるでしょう。
最初に書くべきは、どのようにコードを入手するか、つまりリポジトリーをクローンするのか、パッケージマネージャーを使ってインストールするのかです。途中で困ってしまう人がいないように、役立つものにはなんでもリンクを張るのを忘れずに。
APIのドキュメントを書く時は、明確でシンプルにしましょう。つまり、多くの人が使うであろうユースケース、つまり王道(happy path)を最初に書くということです。これで、全てが初めてのユーザーにしっかりと焦点を合わせた形になります。今回は、メソッドの引数と戻り値を、例とともに理想的な形で説明しています。明瞭であればあるほど、質問が少なくなります。
王道の方法を書き切ったら、エッジケースとともに、ユーザーが遭遇しやすいエラーについてもドキュメントを書くと便利です。これはドキュメントの最後に副項目として書くことになり、既にインストールが済んでプロジェクトを使っている人に対して有用です。困ったり混乱しているユーザーが検索しそうなキーワードを幾つか含んでおくようにしましょう。
貢献(Contributing)
READMEのこの部分は重要で、ユーザーがコントリビューターになってくれるかどうかに違いが出てきます。CONTRIBUTINGファイルがあるとしても、GitHubやオープンソースについての前提知識がないと、ユーザーはそれを見つけてはくれないでしょう。この節は基本的なところを押さえ、それからCONTRIBUTINGファイルがあるならそこへのリンクを張るというようになっているべきです。
ここでも自分のために、テストの実行方法やプルリクエストを受け入れる基準について簡単に書いておきましょう。これで、レビューや受け入れのプロセスが摩擦の少ないものになるでしょう。
またここは、行動規範(code of conduct)があるならそこへのリンクを入れるべきところでもあります。新しいコントリビューターが居心地がよく、何か問題があるならそれが解決されるようにしてあげましょう。行動規範のよい例として、Contributor Covenantがあります。
サポートとバージョンアップ(Support and Migration)
プロジェクトのサポート状況について書いた節はとても役立ち、メジャーバージョンが違うものをリリースした後ならなおさらです。多くは、プロジェクトのメジャーバージョン間のバージョンアップで手助けを必要としている既存ユーザーにとって便利な節です。
完全なバージョンアップガイドはREADMEに追加するにはちょっと長すぎるかもしれません。私はプロジェクトのリポジトリーのルートにMIGRATIONファイルを置いて、この節からリンクしています(pa11yの例を見てみてください)。
古いバージョンのサポート計画があるなら、概要をここに書きましょう。また、メジャーリリースとそのサポート終了日を書くシンプルなテーブルを作っても良いでしょう。
ライセンス(License)
最後に、著作権表示とプロジェクトが採用しているライセンスへのリンクを置くべきです。多くのユーザー、特に大きな組織で働いている人にとっては、この情報がないとプロジェクトを使うことすらできません。LICENSEファイルを配布しているとしても、ここにリンクを含めておくのは役立つでしょう。
その他の節
ここまでで取り上げたのは、READMEに書けることの全てではありません。私のプロジェクトで使っている他の節としては以下があります。
- なぜ？(Why?) あなたのプロジェクトが既に他のプロジェクトでできることをやっていたり、特に複雑な時には、なんらかの理由を提供しておくのは役に立ちます。
- よくある質問(Common Questions) よくある質問を書くところで、同じようなイシューが作られるのを防げます。
- 例(Examples) コード例やサンプルアプリケーションを動かす方法へのポインターです。
- 謝辞(Thanks) 技術的なところ以外でプロジェクトに貢献してくれた人を列挙して感謝する節です。
- 更新履歴(Changelog) プロジェクトの更新履歴の記述自体あるいはリンクです。
完全なREADME
これで読みやすいREADMEができました！こちらでその全文が見られます。
私は、もっとドキュメントを書く人がユーザーの欲しいものについて考えを巡らせて欲しいと思っています。もし何か足りないと思われるところがあれば教えてください。役立つREADMEを作るためのあなたのヒントや意見を聞きたいと思っています。
