人にやさしく。作ったものにはREADMEをつけよう。
人に優しく。 きっと2週間後の自分も他人だから。
忘れてもいいように、いろいろと思い出せるように、ドキュメントを残しましょう。ただいざドキュメント作成をしようとすると「めんどくさいな」って思い結局作成しないこともあります。この原因はいくつもあるとは思いますが、そもそも一体何を書けばいいんだ？？？と悩んでしまうう人は多いのではないでしょうか？
少しでも悩みが減るようにテンプレートを用意しました。 テンプレートだけでは味気ないので、テンプレートの各セクションごとに作成意図を解説します。
READMEのテンプレート
個人的に、マークダウンが好きなのでマークダウンで用意しています。日本語・英語版のテンプレートを用意しました。
日本語ver
# ツール・ライブラリの名前
概要概要概要概要概要概要概要概要概要概要概要概要概要概要概要概要
## 簡単な説明
簡単な説明簡単な説明簡単な説明簡単な説明簡単な説明簡単な説明簡単な説明
簡単な説明簡単な説明簡単な説明簡単な説明簡単な説明簡単な説明簡単な説明
簡単な説明簡単な説明簡単な説明簡単な説明簡単な説明簡単な説明簡単な説明
簡単な説明簡単な説明簡単な説明簡単な説明簡単な説明簡単な説明簡単な説明
### デモ
## 機能
- 機能1（UI/計算 etc ...）
- 機能2
- 機能3
- ...
他の機能はこちらを参照して下さい。（リンクやヘルプコマンドなど）に
$ awesome-tool --help
## 必要要件
- 要件
- 要件
- 要件
- ...
## 使い方
1. 使い方
2. 使い方
3. 使い方
## インストール
$ git clone https://github.com/TomoakiTANAKA/awesome-tool
$ cd awesome-tool
$ sh setup.sh
$ ~~do anything~~
## テスト
1. 使い方
2. 使い方
3. 使い方
## デプロイ
1. デプロイ
2. デプロイ
3. デプロイ
## その他
その他その他その他その他
その他その他その他その他
その他その他その他その他
その他その他その他その他
## 作者
[@TanakanoAnchan](https://twitter.com/TanakanoAnchan)
mail to: xxxx@mail.com
## ライセンス
[MIT](https://TomoakiTANAKA.mit-license.org)
解説
ツール・ライブラリの名前
名前 + 一言でいうと、どんなツール・ライブラリなのか、を記述します。
簡単な説明 / 機能
ライブラリやサービスがどんな問題を解決できるのか、記述します。 イメージを付けるために、画像や動画を用意したいものです。
機能に関しては、代表的な機能を列挙します。 人間の頭に残りやすい数として、3つほどに集約するのが良いです。
必要要件
Windowsでしか動かないよ、MacOSでしか動かないよ、など条件がある場合は書きましょう。知らずに使ってみて、使えなかったショックは計り知れないです（個人談）。
使い方
文字通り使い方を説明します。 幾つか簡単かつよく使う・代表的な機能の説明を記述します（で、お前のライブラリは何ができるの？をきちんと伝えるため）。
細かな機能や、詳しいパラメータの説明は別途ドキュメントを設けましょう。
インストール / テスト / デプロイ
ライブラリやソフトウェアを使う人は、使い方が書かれていないドキュメントをみてどう思うでしょうか？ 自分にも、他人にも優しくということで、記述します。
コピペでやれる、エラーが出ても理解しやすいように、一行に一コマンドとしたほうが良いです。 時々、ワンライナーで書いているものを見かけますが、何をしているかわかりにくいのでやめたほうがよいです。
いろいろな人が使う可能性があるため、都度説明するコストを省くためにも、きちんと書きましょう。（こちらも経験談）
その他
その他には、文字通りその他の情報を記述したら良いと思います。社内であれば、以下の記述はあったほうが良いと思います。
- Document
- 別途ドキュメントを用意している場合は、そのリンクを
- Ticket
- Redmine等でチケット管理している場合は、そのリンクを
また、特殊な使い方や特別注意しなければいけないこと（特定のOSでクラッシュする、など）を記述します。
作者
連絡が欲しい場合は書いたら良いと思います。GitHubで公開する場合は、該当ページから作者が一目瞭然のケースもあるので不要な場合もあります。ただ、めんどくさがらずに書いたほうがコピペで済みますし優しと思います。
ライセンス
ライセンスは、とりあえずMITで作っていますが、正直違いがわかりません。ゆくゆくは調べて記述したいと思います。
英語版のREADME.md
一応英語版も用意しています。よろしければどうぞ。
# Awesome-name
OverviewOverviewOverview
## Description
DescriptionDescriptionDescription
DescriptionDescriptionDescription
DescriptionDescriptionDescription
***DEMO:***
## Features
- Awesome function
- Awesome UI
- ...
For more information, see \`awesome-tool --help\`.
## Requirement
- Requirement
- Requirement
- Requirement
## Usage
1. Usage
2. Usage
3. Usage
## Installation
$ git clone https://github.com/TomoakiTANAKA/awesome-tool
$ cd awesome-tool
$ sh setup.sh
$ ~do anything~
## Test
1. test
2. test
3. test
## Deploy
1. deploy
2. deploy
3. deploy
## Anything Else
AnythingAnythingAnything
AnythingAnythingAnything
AnythingAnythingAnything
## Author
[@TanakanoAnchan](https://twitter.com/TanakanoAnchan)
mail to: xxxx@mail.com
## License
[MIT](https://TomoakiTANAKA.mit-license.org)
まとめ
READMEはツールやプロジェクトの第一印象を決める重要なドキュメントです。ツールやライブラリを探している時はたいてい幾つかのものを並行して調査しています。そんな際に、ドキュメンの有無やその質が高いことは、採用条件の１つにもなります。
経験則になりますが、きちんとドキュメントを書ける人は以外に少ないので（みんなの興味関心が薄い部分だったりする）、しっかり書いているだけで、一目置かれるかもしれませんね。
参考文献
こちらの記事にインスパイアされて、自分もしっかりドキュメントを残そうということでこちらの記事を書きました。 ありがとうございました。
- わかりやすい README 駆動開発
- 残念ながら現在は404になってしまったようです