社内のレポジトリのreadmeテンプレ

会社で、何かのレポジトリをパカ!って開けて出てくるREADME.mdが、 古い・ふんわり・不思議と一部の説明だけ充実している の3Fであることがあり、仕方ないのだけど(事業が継続した+コードの成長が速い)

情報lessに寄せる方針でなんか整えたいな〜と思い、今年手をつけたレポジトリはついでに手直しした

いろいろ考え落ち着いてきているテンプレこちら

社内のレポジトリのreadmeテンプレ · GitHub

それが(例えばCPANモジュールであるとかで)定番の良いreadmeテンプレがあるジャンルの場合、それに合わせるべき。あとOSSなら"good readme template" とかで検索

ただ、既存社内サービスのアプリケーションコードのレポジトリの場合、そこをパカ!って開けた、やる気溢れる開発者が求めてるのは文章じゃなく

  • これは何なのか(目的のレポジトリか)
  • ローカル開発環境が立ち上がる魔法のコマンドとunit testが走る魔法のコマンド
  • 本番デプロイと確認方法

特に弊社の場合最低ラインこのへんかな〜とおもい上記テンプレになった。

補足

  • DevelopmentとDeploymentという単語が似ているので、トミール内協議の末Developがmentを獲得しました🙂
  • 基本足さないのだけど、適宜design doc的のものを参考にたとえばステート遷移図とかディレクトリガイドとかを足すこともある。
  • ソースコードのコミットがci/cd起点になるので、ビジネス的な詳細とかは、wikiに記載してそこに逃がすようにしてる。
  • CI/CDツールにオシャレバッヂがあればそれもつけている。
  • べつにコマンドはmakeじゃなくてもよい

これがいいのは、

なんか
すごい
わかった気になる
図

この図がホワイトボードの写真とかでも良くて、比較的楽に整然とできあがるところ

いまのところそこまで流行ってるわけではないのだが、今年を振り返りつつ可能な範囲なのでgistにupしてブログに書いてみた次第だ