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