概要
散らかっていたGitHubを整理して、きっちりしたREADMEを書いたので、その方法をまとめました。
一度フォーマットを決めておけば後々楽になるので、ぜひこれを読んでイケてるREADMEを作成してみてください。
READMEの構成
色々と調べた結果、このような基礎構成になりました。
# name
image or gif
## Overview
## Requirement
## Usage
## Features
## Reference
## Author
[twitter](https://twitter.com/Kotabrog)
## Licence
[MIT](https://......)
必要があれば、これに付け加えていく感じです。
私のGitHubになりますが、例えばこんな感じになります。
以下ではそれぞれについて簡単に解説をいたします。
name
私は基本的にrepository nameを書いています。
image or gif
やっぱり最初にイメージがあるとインパクトがありますからね。差し込み方はこんな感じです。
Overview
ここには概要を書いています。基本的に１～２行くらいに収まるようにします。
Requirement
環境や、必要なライブラリなどについて言及しています。
……とはいっても、場合によっては動作確認をした環境だけ載せているという感じで、必ずしも必要としてない条件も載せてしまっています。
例えば以下のように示しています。
必要があればバージョンなども載せています。
- macOS
- clang
- Docker 19.03.6
Usage
簡単な使い方です。
Features
詳しい仕様について、基本的に箇条書きで紹介しています。
Usageで紹介しなかった詳しい使い方も書いています。
箇条書きで書きづらい場合や、長くなりそうな場合には、「Features」ではなく「Description」に変更したほうが個人的にはピンときます。
Reference
参考URLを書きます。
Author
自分の情報を載せています。
私はTwitterのアカウントなんかを載っけています。
Licence
Licenceについて載せています。例えば以下のような感じです。
[MIT](https://......)
Licenceについて
Licence、何それ、おいしいの？と思っていたのですが、READMEを作るために調べていたら以下のよう言葉を見かけました。
著作権を主張しないつもりなんだったらそれを明示的に宣言して欲しい。ライセンスが明示されていないのは、どんなライセンスよりも厳しいライセンスだ。
（Ruby 1.9.2リリースとWEBrick脆弱性問題の顛末より）
たしかに、明記されていないと著者の意向がわからないですものね。
せっかくプログラムをGitHubに載せたのなら、色々な人に使ってもらいたいし、できれば著者へのリンクをつけていただいたり、紹介していただきたい……と思ったので、私はできるだけ制限のないライセンスである「非コピーレフト型」の「MIT」を選択しました。
Licenceについて詳しくは以下の参考URLをご参照ください。
gifについて
ページの最初に画像があるとインパクトがありますが、それが動いていたらなおのことインパクトがあります。
しかし、gif画像なんて作ったことない……という方に、簡単に作れるサイトをご紹介します。
LICEcapはディスプレイに写っているものを簡単にgif画像にすることができるアプリです。
BannerKoubouは、gif画像を編集することができるWebサイトです。
使い方としては、最初にLICEcapでディスプレイに表示しているものをgif画像にして、その後で、前後の部分やもたついている部分をBannerKoubouで切り取るといい感じのgif画像を簡単に作ることができます。
ぜひお試しください！
Markdownについて
READMEで使えるMarkdownのチートシートは、以下のものがわかりやすかったです。
また、READMEの書き方についても参考にさせて頂いたこちらの記事では、htmlやcssの書き方を利用した画像の貼り方も紹介しているので、ぜひ御覧ください。
おわりに
プログラムを書くことが忙しくて、READMEなどはおろそかにしてしまいがちですが、この投稿がそんな忙しいエンジニアの手助けになれたら嬉しいです。
（いっぱい調べたので、見てほしい）。