会社で何かのレポジトリをパカ！って開けて出てくるREADME.mdが「古い・ふんわり・不思議と一部の説明だけ充実している」の3Fであることがあり、それは事業が継続した＋コードの成長が速いので仕方ないのだけど、lessに寄せる方針でなんか整えたいな〜と思い、今年コードに手をいれたレポジトリはついでに手直しした
いろいろ考え落ち着いてきているテンプレこちら
tomill/internal-repo-readme-boilerplate.md
https://gist.github.com/tomill/083952e876249315c7c4aa6c38e1d61f
OSSならテンプレートがあるのですが、既存社内サービスのアプリケーションコードのレポジトリの場合、そこをパカ！って開けた、やる気溢れる開発者が求めてるのは整った量のある文章じゃなくこの辺かと思い上記テンプレになった。
- これは何なのか（目的のレポジトリか）
- ローカル開発環境が立ち上がる魔法のコマンドとunit testが走る一発目のコマンド
- 本番デプロイと確認方法
補足
- DevelopmentとDeploymentという単語が似ているので、トミール内協議の末DevelopがDevを獲得しました🙂
- 基本足さないのだけど、適宜design doc的のものを参考にたとえばステート遷移図とかディレクトリガイドとかを足すこともある。
- ソースコードのコミットがci/cd起点になるので、ビジネス的な詳細とかは、wikiに記載してそこに逃がすようにしてる。
- べつにコマンドはmakeじゃなくてもよい
これがいいのは、
なんか
すごい
わかった気になる
図
この図がホワイトボードの写真とかでも良くて、比較的楽に整然とできあがるところ
いまのところそこまで流行ってるわけではないのだが、今年を振り返りつつ可能な範囲なのでgistにupしてブログに書いてみた次第だ