READMEの重要性
READMEというのは、GitHubで公開されるソフトウェア（リポジトリ）の説明書きのことなのですが、これを軽視している人が多く凄い勿体無いなと感じることが多いです（GitHubって何？という人は下記記事参照下さい）。
個人的には、ソフトウェアにちょっとした機能を追加したり、デザインを工夫するよりも、READMEを書くことに注力した方がずっと効果が高いと思っています。当たり前の話ですが、どんな良いソフトを作っても、そもそもそのソフトが何なのかとか、使うとどんな良いことがあるのか、どうやって使うのかが分からないと、せっかく公開しても他の人に伝わりようがないですからね。実際、GitHubを見ていて、たくさんStarがついているリポジトリは、READMEが充実していることが多いと感じます。
といいつつ、自分も結構READMEを手を抜いてしまったり、毎回書く項目が変わってしまったりしているので、自分への自戒を込めてREADMEを書くときに気をつけていることをまとめて、テンプレート化してみたいと思います。
ちなみに、この記事では基本的に趣味でソフトウェアを公開している人を対象としていますので、その点はご承知おき下さい。
README書くときに気をつけていること
最初にどんなソフトなのかをできるだけ丁寧に説明する
当たり前のようですが、意外にそもそも公開しているソフトが何なのかを説明していないリポジトリがたくさんあります。
多くの人に使って欲しい場合はここをできるだけ丁寧に書くのが重要です。また、GUIがあるソフトウェアなら、スクリーンショットを貼り付けると、どんなソフトかイメージができるので良いと思います。
自分の場合ですと、魚眼画像を広角画像に変換する「uonome」というソフトがあるのですが、そちらのリポジトリでは以下のように、ソフト起動したときのスクリーンショットと、変換前、変換後の画像を載せることで、どのようなソフトか一目で分かるようにしています。
決して大したソフトでは無いのですが、このリポジトリにStarが（自分にしては）たくさんついているのは、使う人が簡単に何のソフトかイメージできるというところが大きいのではないのかなと考えています。画像だと言語関係なく多くの人に理解してもらえるのも良い点ですね。
画像の代わりに動画を使うのも効果的と思います。動画はGIFアニメの他、動画ファイルもアップロードすることができます。GIFアニメを作るときは、Macで無料で使える「PicGIF Lite」を使います。
動画の場合は、READMEにドラッグアンドドロップするだけでOKです。なお、ファイルサイズは10MB以下にする必要があります。以下動画を貼り付けたREADMEです。
参考：flash - How to embed a video into GitHub README.md? - Stack Overflow
アイキャッチ画像の設定
目を引くアイキャッチ画像をつけると良いかもしれません。気合い入れたソフトの場合は、ロゴなどあると良いと思います。
アイキャッチ画像は、GitHubのOGP画像として設定すると、Twitterでリンクされたときにアイキャッチ画像が表示されて、目を引きやすくなります。
OGP画像の設定方法は以下参照ください。
以下で確認できます。
できるだけ英語で書く
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サイトで使い方などを説明しています。
GitHub Pagesに関しての説明や使い方は以下記事参照ください。
ライセンスを明示する
これも地味に重要です。ライセンスを表示しないと、他の人がそのソフトを使うことが出来なくなってしまいます。正確に言うと、例えばそのソフトを勝手に使って公開すると、それを作成した作者によって訴えられるリスクを抱えることになります。
「ネットに公開してるからそんなん気にしないよ」
という人もいたりするのですが、使う人からしてみるとライセンスという形で意思を明示されていないと判断しようがないのですよね。なので、もし特に問題ないのであれば、MITライセンスで公開しておくとソフトウェアの世界をより良くする貢献になると思います。GitHubだと、リポジトリを作成するときにライセンスのオプションがあるので、ライセンス選択してチェックするだけでライセンスファイルを作成できます。
ライセンス表記がないリポジトリに対してどうするかというと、私はそのままの使用を諦めるか、どうしてもという場合は思い切って作者に問い合わせてみたりします。以下記事でも、作者に問い合わせてライセンスの明示いただいた箇所があります。
READMEの書き方で参考になるサイトを調べる
その他、READMEの書き方で参考になるサイトを紹介します。
READMEの書き方が優れているリポジトリを集めたGitHubのリポジトリです
READMEの書き方から始まり、READMEを書くためのMarkdown記法に関する情報や、READMEへの画像の表示の仕方など多くの有用な情報がまとまっています
Markdown形式の書き方のルールをまとめたページです。VS Codeエディタで拡張を入れると自動でチェックすることも可能です。こちらの記事を参照ください。
READMEテンプレート
いちいち、上記を全部チェックするのも大変なので、テンプレートを作っておいて基本流用するのが漏れもなくて便利ですね。最近私が新しいリポジトリを作ったときREADMEに書くのは以下のような項目です。
もちろんこれで完璧というものでは全くなくて、READMEは、そのソフトウェアの目的やターゲットに合わせて変えていくべきと思います（例えば仕事で複数の人が開発する場合は、他にも色々なドキュメントの情報を記載する必要あると思います）。また、テンプレート自体も常に見直してバージョンアップしていくべきと考えています。
最初にアイキャッチ画像などを表示 # リポジトリ名 このソフトはどんなもので、何ができるのかを書く 合わせて、簡単なデモ（使用例）などスクリーンショットやGIFアニメで表示 ## Dependency 使用言語とバージョン、必要なライブラリとそのバージョンを書く Pythonならrequirements.txtを用意するのも良い ## Setup セットアップ方法を書く。用意するハードウェアとソフトウェアをセットアップするためのコマンドを記載する ## Usage 使い方。なるべく具体的に書く。サンプルも書く ## License This software is released under the MIT License, see LICENSE. ## Authors 作者を明示する。特に、他者が作成したコードを利用する場合は、そのコードのライセンスに従った上で、リポジトリのそれぞれのコードのオリジナルの作者が誰か分かるように明示する（私はそれが良いと思い自主的にしています）。 ## References 参考にした情報源（サイト・論文）などの情報、リンク
Pull Requestやissueのテンプレート
READMEとは少し異なりますが、GitHubではPR(Pull Request)やissueのテンプレートを.githubディレクトリを作って設定することができます。また.githubリポジトリを作成すると、アカウント全体にデフォルトのテンプレートとして適用することも可能となります。詳しくは、以下の記事を参照ください。
まとめ
重要なのに意外と軽視されがち（と私が思っている）READMEの書き方に関してまとめてみました。個人的には、もの凄い良いソフトやライブラリだけど、READMEやサンプルが不足していて埋もれているものが多いなと思っています。
開発と発信（営業）を両方やるのは大変ですが、少し手をいれるだけで多くの人に使ってもらえたり、一緒にソフトを開発してくれる人（プルリクエストしてくれる人）がグッと増える可能性があるので、他の人に使ってもらったり、プルリクエスト欲しいけどREADMEに何も書いてないという人は、一度記載してみたりブログで発信してみることをオススメいたします。
参考リンク
関連記事
変更履歴
- 2021/08/28 動画の貼り付けに関して追記
- 2021/03/19 アイキャッチ画像のOGP設定に関して追記
