人にやさしく。作ったものにはREADMEをつけよう。

 

人に優しく。
きっと2週間後の自分も他人だから。

忘れてもいいように、いろいろと思い出せるように、ドキュメントは書いておきましょう。
ドキュメントのめんどくさいなって結局書かない原因の1つに、一体何を書けばいいんだ???と悩んでしまうところではないでしょうか。

少しでも悩まないようにテンプレートを用意しました。
テンプレートだけでは味気ないので、テンプレートとその意図を解説します。

READMEのテンプレート

僕は個人的にですが、マークダウンが好きなのでマークダウンで用意しています。
こちらの記事にかなり影響を受けています。

英語

  • README.md

日本語ver

解説

ツール・ライブラリの名前

名前 + 一言でいうと、どんなツール・ライブラリなのか、を記述します。

簡単な説明 / 機能

ライブラリやサービスがどんな問題を解決できるのか、記述します。
イメージを付けるために、画像や動画を用意したいものです。

機能に関しては、代表的な機能を列挙します。
人間の頭に残りやすい数として、3つほどに集約するのが良いです。

必要要件

Windowsでしか動かないよ、MacOSでしか動かないよ、など条件がある場合は書きましょう。
知らずに使ってみて、使えなかったショックは計り知れないです(個人談)。

使い方

文字通り使い方を説明します。
幾つか簡単かつよく使う・代表的な機能の説明を記述します。(で、お前のライブラリは何ができるの?をきちんと伝えるため)
細かな機能や、詳しいパラメータの説明は別途ドキュメントを設けましょう。

インストール / テスト / デプロイ

ライブラリやソフトウェアを使う人は、使い方が書かれていないドキュメントをみてどう思うでしょうか?
自分にも、他人にも優しくということで、記述します。

コピペでやれる、エラーが出ても理解しやすいように、一行に一コマンドとしたほうが良いです。
時々、ワンライナーで書いているものを見かけますが、何をしているかわかりにくいのでやめたほうがよいです。

特に社内の場合は、いろいろな人が使ういますが、都度説明するコストを省くためにも、きちんと書きましょう。

その他

その他には、文字通りその他の情報を記述したら良いと思います。社内であれば、以下の記述はあったほうが良いと思います。
* Document – 別途ドキュメントを用意している場合は、そのリンクを
* Ticket – Redmine等でチケット管理している場合は、そのリンクを

また、特殊な使い方や特別注意しなければいけないこと(特定のOSでクラッシュする、など)を記述します。

作者

連絡が欲しい場合は書いたら良いと思います。GitHubで公開する場合は、該当ページから作者が一目瞭然のケースもあるので不要な場合もあります。
ただ、めんどくさがらずに書いたほうがコピペで済みますし優しと思います。

ライセンス

T.B.D
ライセンスは、とりあえずMITで作っていますが、正直違いがわかりません。ゆくゆくは調べて記述したいと思います。

まとめ

READMEはツールやプロジェクトの第一印象を決める重要なドキュメントです。
ツールやライブラリを探している時はたいてい幾つかのものを並行して調査しています。
そんな際に、ドキュメンの有無やその質が高いことは、採用条件の1つにもなります。

社内においては、きちんとドキュメントを書ける人は以外といなかったりするので(みんなの興味関心が薄い部分だったりする)、しっかり書いているだけで、一目置かれるかもしれませんね。

参考文献

こちらの記事にインスパイアされて、自分もしっかりドキュメントを残そうということでこちらの記事を書きました。
ありがとうございました。

わかりやすい README 駆動開発

  • このエントリーをはてなブックマークに追加
  • Pocket

この記事へのコメントはこちら

メールアドレスは公開されませんのでご安心ください。
また、* が付いている欄は必須項目となりますので、必ずご記入をお願いします。

内容に問題なければ、下記の「コメント送信」ボタンを押してください。