詳細設計書を捨てるには

※ウェブエンジニアとしての意見

まず前提として詳細設計は捨てられるなら捨てたほうが良いと思ってる。以下理由

平時のメンテナンスはそこそこ問題なく行えるが、多忙時や緊急性の高いアクシデントが発生した場合の修正は設計書修正まで含めずPR単位でのみ行うことが多く、ソースコードとの乖離が生まれる。

乖離量が増えると同時に設計書を適切に修正する難易度が跳ね上がっていくため、メンテナンスコストが増えやすい。

また単純にPR作成のたびに設計書修正も重なってくるため工数が増える。

そもそも仕事の成果はoutput / inputで測れると考えているので、input量の増える詳細設計は捨てたい。

誰かの頭の中かドキュメントかあるはずなので、ゼロイチ時点であったとしてもissueに言語化した要件を書き下すだけであとは開発者にどう実装するかは委ねてよいと思う。

ただここでスキルでの差が発生してしまうため、開発ガイドラインは固めておく必要がある。コーディング規約など

また外部APIなどを利用している場合は、そのドキュメントなどのリソースをまとめた情報も必要になる。

こういった情報をwikiで整理し管理しておけば、管理コストの低い情報のみで成果物を生み出すことが可能になるはず

基本設計は必要だと思う。DBは何があるか、APIのリクエストレスポンス、画面定義書など。ただこのあたりは自動生成する方法があるので、実装ベースで更新をかけていくことが可能。

システム全体の構成図や機能一覧については客がいるなら作ったほうがいいような気がするけど、いないならいらなくね？とは思う。システム構成図はIaCが実質ドキュメントの役割を果たせると思ってるので。

機能一覧は若干必要な気もするけどウェブだったらルーティングファイルが十分にその役割を果たしてくれるのでは？と思う。何をするページなのかまでは不明なので、前提知識量の多いものであれば別途情報を管理する必要がある気はする

wikiに共通して必要な情報を整理し、それをもとに成果物を生み出すことができれば工数を削れるのでよいと考えた。

wikiには以下辺りをざっと書いておくといい気がした

後々更新がかかりそうな情報については粒度粗目に書いたほうが良い。更新コストが伸びるので

プロジェクト情報辺りは怪しいので粒度粗目でいいと思う

テストコードとソースコード。

テストコードで観点が見えたり、ソースコード自体を見れば特定処理の実装は十分にわかる。

詳細設計の有利点はソースコードを見るより設計書を見たほうが早く理解できるという部分にあると思うが、ぶっちゃけよく見かける詳細設計、日本語でプログラミングしただけでは？みたいなもの多いのでむしろ読みにくい。関数なども使わずに一息に書き下したソースコードを見てる気分になる

開発ガイドラインを十分に書きこんで周知し、またレビュープロセスを適切に運用すれば詳細設計書不要でコードベースで概要把握可能でしょと考えた。

---

ソースコードと1:1の関係になってる詳細設計書、ソースコード見ればええやん！としか思わないので、成果最大化のためにも捨てたほうがいいと思う。

ゼロイチで開発するシーンやウォーターフォールで開発するシーンでいるでしょ。となるのは若干分からないでもないけど、issueに言語化されたものを載せれば十分な気がしてる。

ただバリデーションやエラー文言、画面仕様どうするかなど細かい点を考えるとゼロイチ時点では欲しいよなぁとなるのはめっちゃわかる。

ここに関してはテストコードベースで読み解けばいい気がする。

要はどのような観点でテストするかをissueで言語化し、それをもとに実装者がテストコードを書く。そのテストコードをレビュアーが確認し、バリデーションやエラー文言などの部分が適切であるか評価する。的な

どんなエラー文言とするかは共通化したほうがいいような気もするので、wikiでドキュメント化しておくといいのかなぁという気がする。

少なくとも各機能ごとに書かれた詳細設計書でそれぞれエラー文言を書き下している状態よりはそのほうがいい気がする。

ウォーターフォール開発ではどうしても詳細設計書を捨てる選択肢は難しいし、客がいる場合はそれを作っておくことも仕事の一つとして含まれていたりする場合もある。

ただ仕事は成果という部分だけに重きを置くべきだと思ってるし、成果はoutput / inputで評価できるものだと思っているので、捨てても開発できるはずのものをわざわざ含めてinputを増やして成果を下げるのはよくないと思った次第でした。おわり

INTP型のブログ