はじめに
今時のIT企業でソフトウェアをビジネスの主としている会社は、従業員の入れ替えが発生しても、その時の意思決定がなぜ行われたのかも含め、情報を把握できるようにしたい。
事業を営むと、例えばテーブルが追加されたり項目が変更されたり、クラウドサービスやfirebaseなどのMBaaSツールが廃止になったりアップグレードになり、修正しないと動かなくなったりする。
なので、外部環境の変化を受け修正する必要があるので
- なぜそういう設計をしたのか(まともなエンジニアなら理由を書く。xxを達成するため & 考慮するためそういう設計をした、とか言う)
- なぜそのサービスを利用したのか(利用事例が多い or 費用の面で採用せざるを得なかった、とか色々ある)
等のドキュメントが必要。
githubのプルリクに書く件について
僕の会社ではgithubのプルリクにそれを書いている。 メリットとして
- マークダウンなので書きやすい
- ソースコードからすぐ該当箇所のプルリクに飛べるので、その時の背景を知れる
などのメリットがある。
メンバーがコードレビューをする時、その背景も含めて理解しやすい。
欠点
非エンジニアは閲覧し辛い。 もし非エンジニアもそれを見れたら、運用側の人や営業側、経理の人なども見れて助かるかもしれない。
また、プルリクに書くと、プルリク検索から探せたりもするが、タイトル検索では引っかかると思うが、しれっと変更されたものや、細かい所の検索制は低い気がする
esaで全てを記述する場合
esaで全てを記述する方法についてなのだが、その場合非エンジニアも見やすい。
しかし、ソフトウェアの変更を加えるエンジニアがレビューするものと別で管理することになるデメリットはある。 コードベースでの使用はgithubに残して、運用ベースやユースケース、仕様ベースではesaに残した方が良いように思える。
slackやgoogleツールを採用する場合
slackはリアルタイムの会話で使うもので、ラフなものや手がかりを残すもの、という意味では優れている。
しかし詳細を残すのには向いてない。
goggleツールは、スプシなど必須のものと一緒に使えるのはメリットではあるが、手軽さやエンジニア向けのツールではない。
非エンジニアには良いツールだと思うが(硬いフォーマットとか)
