READMEの良さそうな書き方・テンプレート【GitHub/Bitbucket】

READMEの重要性

 READMEというのは、GitHub/Bitbucket等で公開されるソフトウェア(リポジトリ)の説明書きのことなのですが、これを軽視している人が多く凄い勿体無いなと感じることが多いです(GitHub/Bitbucketって何?という人は下記記事参照下さい)。

 個人的には、ソフトウェアのちょっとしたデザイン工夫するよりは、READMEを書く方に注力した方がずっと良いと思っています。当たり前ですけど、どんな良いソフトを作っても、そもそもそのソフトが何なのかとか、使うとどんな良いことがあるのか、どうやって使うのかが分からないと、せっかく公開しても他の人に伝わりようがないですからね。実際、GitHubとか見ていると、たくさんStarがついているリポジトリは、ほとんどがREADMEが充実しています。

 といいつつ、自分も結構READMEを手を抜いてしまったり、毎回書く項目が変わってしまったりしているので、自分への振り返りを込めてREADMEを書くときに気をつけていることをまとめて、テンプレート化してみたいと思います。

 ちなみに、この記事では基本的に趣味でソフトウェアを公開している人を対象としていますので、その点はご承知おき下さい。

README書くときに気をつけていること

最初にどんなソフトなのかをできるだけ丁寧に説明する

 当たり前のようですが、以外にこれをしていないリポジトリがたくさんあります。また、多くの人に使って欲しい場合はここをできるだけ丁寧に書くのが重要です。また、GUIがあるソフトウェアなら、スクリーンショットを貼り付けると、どんなソフトかイメージができるので良いと思います。

 自分の場合ですと、魚眼画像を広角画像に変換する「uonome」というソフトがあるのですが、そちらのリポジトリでは以下のように、ソフト起動したときのスクリーンショットと、変換前、変換後の画像を載せることで、どのようなソフトか一発で分かるようにしています。

f:id:karaage:20180103121346p:plain:w640

f:id:karaage:20180103121359j:plain:w640

f:id:karaage:20151219221425j:plain:w640

 決して大したソフトでは無いのですが、このリポジトリにStarが(自分にしては)たくさんついているのは、使う人が簡単に何のソフトかイメージできるというところが大きいのではないのかなと考えています。画像だと言語関係なく多くの人に理解してもらえるのも良い点ですね。

 画像の代わりにアニメGIFを使うのも効果的と思います。私はMacで無料で使える「PicGIF Lite」を使います。APP Storeからダウンロードできます。

できるだけ英語で書く

 READMEはできるだけ英語で書くようにしています。当たり前ですが、英語と日本語では読める人の数の規模が全然異なるので英語の方が見てもらえるチャンスが大きくなります。たまーに外国の方からもStarもらったりforkしてもらっているので、私の怪しい英語でもなんとか通じているのかなと自己評価しています。

 ただ、当たり前ですが日本人だけをターゲットにしているなら日本語でも良いとは思います。どうしても使いたい人は、Google翻訳使うでしょという割り切りもありかなとも思います。私もブログは日本語で書いていますしね。

ソフトの動作・開発に必要なライブラリ・環境を書く

 これも重要です。よくあるが、良さそうなソフト見つけて試してもエラーが大量に出て、ソフトが間違っているのか、環境が合ってないのかがまず分からなくて、諦めてしまうケースです。

 例えばPythonだとPython2とPython3では互換性ないですし、使用しているライブラリのバージョンによっても動いたり動かなかったりします。特に最近流行りの機械学習系のライブラリでは、マイナバージョンの違いでも動かないケースが多くあるので、ちゃんと提示してあげるのが親切です。以下コマンドで書き出したrequirements.txtをソフトと一緒に公開している例もよくありますね(ただし、必須ライブラリ以外は削除しておいてあげるのが親切です)。

$ pip freeze > requirements.txt 

 使用する場合は、以下コマンドで必要ライブラリ一気にインストールできますし、requirements.txtファイル見るだけでも、バージョン確認できて便利です。

$ pip install -r requirements.txt

 Pythonに関しては、その他以下記事が色々参考になると思います。

使い方をできるだけ詳しく書く

 当たり前ですが、これも結構書かれていないソフトが多いです。

 入力、出力を書くことは当然ですが、CLI(コマンドラインインターフェース)のソフトなら、具体的なコマンド例を書いてあげると初心者にはわかりやすいと思います。

 あんまりにも長くなってしまい冗長になる場合は、ブログなどで詳しく書いてそちらへのリンクを貼るという方法も良いかなと思います。あくまで、GitHubで完結させたい場合は、「GitHub Pages」を活用するのもオススメです。

 私の場合は、Pythonでの画像処理のサンプルを公開している「python-image-processing」というリポジトリがあるのですが、サンプルの数が多くなってきたので、以下のGitHub Pagesサイトで使い方などを説明しています。

python-image-processing

 GitHub Pagesに関しての説明や使い方は以下記事参照ください。

ライセンスを明示する

 これも地味に重要です。ライセンスを表示しないと、他の人がそのソフトを使うことが出来なくなってしまいます。正確に言うと、例えばそのソフトを勝手に使って公開すると、それを作成した作者によって訴えられるリスクを抱えることになります。

「ネットに公開してるからそんなん気にしないよ」

 という人もいたりするのですが、使う人からしてみるとライセンスという形で意思を明示されていないと判断しようがないのですよね。なので、もし特に問題ないのであれば、MITライセンスで公開しておくとソフトウェアの世界をより良くする貢献になると思います。GitHubだと、リポジトリを作成するときにライセンスのオプションがあるので、ライセンス選択してチェックするだけでライセンスファイルを作成できます。

 ライセンス表記がないリポジトリに対してどうするかというと、私はそのままの使用を諦めるか、どうしてもという場合は思い切って作者に問い合わせてみたりします。以下記事でも、作者に問い合わせてライセンスの明示いただいた箇所があります。

READMEの書き方で参考になるサイトを調べる

 その他、READMEの書き方で参考になるサイトを紹介します。

GitHub - matiassingers/awesome-readme: A curated list of awesome READMEs
READMEの書き方が優れているリポジトリを集めたGitHubのリポジトリです

GitHubのREADME.mdを書くときに参考になった記事まとめ - 技術を磨くだいぱんまん
READMEの書き方から始まり、READMEを書くためのMarkdown記法に関する情報や、READMEへの画像の表示の仕方など多くの有用な情報がまとまっています

READMEテンプレート

 いちいち、上記を全部チェックするのも大変なので、テンプレートを作っておいて基本流用するのが漏れもなくて便利ですね。最近私が新しいリポジトリを作ったときREADMEに書くのは以下のような項目です。

 もちろんこれで完璧というものでは全くなくて、READMEは、そのソフトウェアの目的やターゲットに合わせて変えていくべきと思います(例えば仕事で複数の人が開発する場合は、他にも色々なドキュメントの情報を記載する必要あると思います)。また、テンプレート自体も常に見直してバージョンアップしていくべきと考えています。

最初にアイキャッチ画像などを表示

# リポジトリ名
このソフトはどんなもので、何ができるのかを書く
合わせて、簡単なデモ(使用例)などスクリーンショットやGIFアニメで表示

# Dependency
使用言語とバージョン、必要なライブラリとそのバージョンを書く
Pythonならrequirements.txtを用意するのも良い

# Setup
セットアップ方法を書く。用意するハードウェアとソフトウェアをセットアップするためのコマンドを記載する

# Usage
使い方。なるべく具体的に書く。サンプルも書く

# Licence
This software is released under the MIT License, see LICENSE.

# Authors
作者を明示する。特に、他者が作成したコードを利用する場合は、そのコードのライセンスに従った上で、リポジトリのそれぞれのコードのオリジナルの作者が誰か分かるように明示する(私はそれが良いと思い自主的にしています)。

# References
参考にした情報源(サイト・論文)などの情報、リンク

まとめ

 重要なのに意外と軽視されがち(と私が思っている)READMEの書き方に関してまとめてみました。個人的には、もの凄い良いソフトやライブラリだけど、READMEやサンプルが不足していて埋もれているものが多いなと思っています。

 開発と発信(営業)を両方やるのは大変ですが、少し手をいれるだけで多くの人に使ってもらえたり、一緒にソフトを開発してくれる人(プルリクエストしてくれる人)がグッと増える可能性があるので、他の人に使ってもらったり、プルリクエスト欲しいけどREADMEに何も書いてないという人は、一度記載してみたりブログで発信してみることをオススメいたします。

関連記事