開発時に最低限必要な設計系ドキュメント

って、何なんだろうと友人に質問されたので、周りの人に聞いてみた結果をざっくりまとめてみました。

ちなみに、自社サービス開発をしている会社での事例です。 請負開発の場合やエンタープライズ系開発の場合もっと変わってくるかなーと正直思います。

大まかに、以下のドキュメントが揃っていれば、「いきなり知らないプロジェクトにぶち込まれてもなんとかなる」とのことです。

全体像が把握できるもの

• インフラ構成図 / システム間連携図 / ER 図

業務ごとの関連モジュールが把握できるもの

• 業務ごとに分けられた ER 図 / 業務ごとに分けられたクラス図*1
  • 具体的にどこを見ればいいのかを教えてくれるドキュメント

要件 / ユーザーストーリーが把握できるもの

• ユーザーストーリーが書かれたチケット / 機能特性に応じたドキュメント
  • System of Record / System of Engagement などがヒントになりそう

一言でまとめると、全体像を把握し、実際に作業に関連のある場所を特定し、実現すべきことを理解するためのドキュメント群だと思います。

いずれもソースコードやテストコードからボトムアップで理解するのが大変な知識だなという印象です。

あとは、あまりにもコードが汚い場合、「それを補助するためのドキュメント」が欲しいとのことでした。 個人的には、あまりにもコードが汚いならコメント書こうぜとか、それが不要になるようなリファクタしとこうぜとか色々思うので、まぁ一旦おいておきます。笑

再度まとめると、

• 全体像（一体全体どうなってるの？）
• 業務ごとの全体像（具体的にはどこを見ればいいの？）
• 仕様（どう動いてれば良いの？）

みたな感じですね！

確かにこれがわかれば、（あまりにも設計や可読性が崩壊してなければ）なんとかなりそうです。

なるほどー。

*1:ER 図があれば十分との意見もあり