作ったものにはREADMEをつけよう。LifeあるWebエンジニアのブログ。仕事観・プレゼン・プログラミング・教育などなど。日々思ったことを綴っています。作ったものにはREADMEをつけよう。2018/01/25人に優しく。2週間後の自分も他人だから。忘れてもいいように、いろいろと思い出せるように、ドキュメントは書いておきましょう。ドキュメントのめんどくさいなって結局書かない原因の1つに、一体何を書けばいいんだ???と悩んでしまうところではないでしょうか。悩まないようにテンプレートを用意しました。テンプレートだけでは味気ないので、テンプレートとその意図を解説します。参考文献READMEのテンプレート僕は個人的にですが、マークダウンが好きなのでマークダウンで用意しています。こちらの記事にかなり影響を受けています。他の機能はこちらを参照して下さい。...他の機能はこちらを参照して下さい。一言でいうと、どんなツール・ライブラリなのか、を記述します。機能ライブラリやサービスがどんな問題を解決できるのか、記述します。イメージを付けるために、画像や動画を用意したいものです。機能に関しては、代表的な機能を列挙します。人間の頭に残りやすい数として、3つほどに集約するのが良いです。必要要件Windowsでしか動かないよ、MacOSでしか動かないよ、など条件がある場合は書きましょう。知らずに使ってみて、使えなかったショックは計り知れないです(個人談)。文字通り使い方を説明します。幾つか簡単かつよく使う・代表的な機能の説明を記述します。(で、お前のライブラリは何ができるの?をきちんと伝えるため)細かな機能や、詳しいパラメータの説明は別途ドキュメントを設けましょう。デプロイライブラリやソフトウェアを使う人は、使い方が書かれていないドキュメントをみてどう思うでしょうか?自分にも、他人にも優しくということで、記述します。コピペでやれる、エラーが出ても理解しやすいように、一行に一コマンドとしたほうが良いです。時々、ワンライナーで書いているものを見かけますが、何をしているかわかりにくいのでやめたほうがよいです。社内の場合は、いろいろな人が使ういますが、都度説明するコストを省くためにも、きちんと書きましょう。その他その他には、文字通りその他の情報を記述したら良いと思います。社内であれば、以下の記述はあったほうが良いと思います。Redmine等でチケット管理している場合は、そのリンクをまた、特殊な使い方や特別注意しなければいけないこと(特定のOSでクラッシュする、など)を記述します。連絡が欲しい場合は書いたら良いと思います。GitHubで公開する場合は、該当ページから作者が一目瞭然のケースもあるので不要な場合もあります。めんどくさがらずに書いたほうがコピペで済みますし優しと思います。ライセンスT.B.Dライセンスは、とりあえずMITで作っていますが、正直違いがわかりません。調べて記述したいと思います。まとめREADMEはツールやプロジェクトの第一印象を決める重要なドキュメントです。ツールやライブラリを探している時はたいてい幾つかのものを並行して調査しています。そんな際に、ドキュメンの有無やその質が高いことは、採用条件の1つにもなります。社内においては、きちんとドキュメントを書ける人は以外といなかったりするので(みんなの興味関心が薄い部分だったりする)、しっかり書いているだけで、一目置かれるかもしれませんね。参考文献こちらの記事にインスパイアされて、自分もしっかりドキュメントを残そうということでこちらの記事を書きました。ありがとうございました。コメントをキャンセルメールアドレスは公開されませんのでご安心ください。付いている欄は必須項目となりますので、必ずご記入をお願いします。コメント内容に問題なければ、下記の「コメント送信」ボタンを押してください。新しい投稿をメールで受け取るPREV:QiitaのAPIを利用して、特定のタグに紐づく記事の一覧を取得。NEXT:おもしろい仕事は待っていてもやってこない。