Documentation for Software engineering
リポジトリに含まれる md ドキュメントを検索しやすくしたい
wiki と github に分かれてしまうので検索が面倒
GitHub の検索で md だけとかいけるかね？
ドキュメントについて考えてみる
目的
コードを読まないでもコードがなにをやっているか把握できる
読みやすいコードであるという前提をおいても、全体像を把握するにはすべてのコードを読む必要がでてくるので、補助するドキュメントは必要では
暗黙知をなくす
作業手順や作業ログは誰かの頭にしかないと、個人への依存度が高くなりよくない
口頭で話した意思決定なども記録しておかないと忘れ去られて後々困ることになりやすい
知見の共有
良いドキュメントとはなにか
このようなドキュメントの種類がありそう。それぞれで良いの定義はことなると思う。
コードのドキュメント
意思決定のドキュメント
作業のドキュメント
コードのドキュメント
少ない方が個人的には良いと思う
コードとドキュメントがずれると悲惨
update しつづけるメンテナンスコストがかかる
コードでわかることをドキュメントにする必要はない
コードだけではわからない、あるいは把握するのに時間がかかる場合がある
そのような実装になった理由、コンテキスト
大きなソフトウェアの全体像
アーキテクチャ、フロー、インターフェース
意思決定のドキュメント
ある意思決定をした理由を残しておかないと、その決定を変更したいときに正しい議論ができない
作業のドキュメント
コードのドキュメント
インフラのアーキテクチャ
DB ER図
シークエンス図
サービス自体を説明するドキュメント
On-board
意思決定のドキュメント
議事録
作業のドキュメント
作業ログ