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