人にやさしく。作ったものにはREADMEをつけよう。
人に優しく。 きっと2週間後の自分も他人だから。
忘れてもいいように、いろいろと思い出せるように、ドキュメントは書いておきましょう。 ドキュメントのめんどくさいなって結局書かない原因の１つに、一体何を書けばいいんだ？？？と悩んでしまうところではないでしょうか。
少しでも悩まないようにテンプレートを用意しました。 テンプレートだけでは味気ないので、テンプレートとその意図を解説します。
READMEのテンプレート
僕は個人的にですが、マークダウンが好きなのでマークダウンで用意しています。 こちらの記事にかなり影響を受けています。
英語
- README.md
\# Awesome-name
OverviewOverviewOverview
## Description
DescriptionDescriptionDescription
DescriptionDescriptionDescription
DescriptionDescriptionDescription
\*\*\*DEMO:\*\*\*
!\[Demo\](https://image-url.gif)
## 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)
日本語ver
\# ツール・ライブラリの名前
概要概要概要概要概要概要概要概要概要概要概要概要概要概要概要概要
## 簡単な説明
簡単な説明簡単な説明簡単な説明簡単な説明簡単な説明簡単な説明簡単な説明
簡単な説明簡単な説明簡単な説明簡単な説明簡単な説明簡単な説明簡単な説明
簡単な説明簡単な説明簡単な説明簡単な説明簡単な説明簡単な説明簡単な説明
簡単な説明簡単な説明簡単な説明簡単な説明簡単な説明簡単な説明簡単な説明
\*\*\*デモ\*\*\*
!\[デモ\](https://image-url.gif)
## 機能
- 機能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\](http://TomoakiTANAKA.mit-license.org)
## 解説
### ツール・ライブラリの名前
名前 + 一言でいうと、どんなツール・ライブラリなのか、を記述します。
### 簡単な説明 / 機能
ライブラリやサービスがどんな問題を解決できるのか、記述します。 イメージを付けるために、画像や動画を用意したいものです。
機能に関しては、代表的な機能を列挙します。 人間の頭に残りやすい数として、3つほどに集約するのが良いです。
### 必要要件
Windowsでしか動かないよ、MacOSでしか動かないよ、など条件がある場合は書きましょう。 知らずに使ってみて、使えなかったショックは計り知れないです（個人談）。
### 使い方
文字通り使い方を説明します。 幾つか簡単かつよく使う・代表的な機能の説明を記述します。（で、お前のライブラリは何ができるの？をきちんと伝えるため） 細かな機能や、詳しいパラメータの説明は別途ドキュメントを設けましょう。
### インストール / テスト / デプロイ
ライブラリやソフトウェアを使う人は、使い方が書かれていないドキュメントをみてどう思うでしょうか？ 自分にも、他人にも優しくということで、記述します。
コピペでやれる、エラーが出ても理解しやすいように、一行に一コマンドとしたほうが良いです。 時々、ワンライナーで書いているものを見かけますが、何をしているかわかりにくいのでやめたほうがよいです。
特に社内の場合は、いろいろな人が使ういますが、都度説明するコストを省くためにも、きちんと書きましょう。
### その他
その他には、文字通りその他の情報を記述したら良いと思います。社内であれば、以下の記述はあったほうが良いと思います。 \* Document - 別途ドキュメントを用意している場合は、そのリンクを \* Ticket - Redmine等でチケット管理している場合は、そのリンクを
また、特殊な使い方や特別注意しなければいけないこと（特定のOSでクラッシュする、など）を記述します。
### 作者
連絡が欲しい場合は書いたら良いと思います。GitHubで公開する場合は、該当ページから作者が一目瞭然のケースもあるので不要な場合もあります。 ただ、めんどくさがらずに書いたほうがコピペで済みますし優しと思います。
### ライセンス
T.B.D ライセンスは、とりあえずMITで作っていますが、正直違いがわかりません。ゆくゆくは調べて記述したいと思います。
まとめ
READMEはツールやプロジェクトの第一印象を決める重要なドキュメントです。 ツールやライブラリを探している時はたいてい幾つかのものを並行して調査しています。 そんな際に、ドキュメンの有無やその質が高いことは、採用条件の１つにもなります。
社内においては、きちんとドキュメントを書ける人は以外といなかったりするので（みんなの興味関心が薄い部分だったりする）、しっかり書いているだけで、一目置かれるかもしれませんね。
参考文献
こちらの記事にインスパイアされて、自分もしっかりドキュメントを残そうということでこちらの記事を書きました。 ありがとうございました。