orangeitems’s diary

クラウドで働くインフラエンジニアの日々の感想です(ほぼ毎日更新)。

設計書はなぜ必要か

f:id:orangeitems:20210502160743j:plain

 

何度か、設計書を書かない現場に行ったことがありまして、その度に炎上し、仕方ないのでさかのぼって設計書を書く経験を何度もしたことがあります。

設計書を書かない理由は、設計書を書く意味をわかっていないからだと思います。一方で、設計書を書く言語能力も欠如しているからだとも思います。

これから作るものに対して、なぜ作るか。どのように作るか。そして達成しなければいけないことは何か。それぞれを、日本語で他人にわかるように文章で書くというのは意外と得意ではない人は多いものです。

得意じゃないのなら作らなくてもいいのかというと全くそんなことはないのですが、できれば作りたくない。目の前のコンピュータと対峙したいし設定する能力はある。そして結局は実装しないと最終的にどんな設計になるのか未確定だから、と言って設計書を書かずにいきなり実装に入ってしまう、そんなパターンばかりだったように思います。設計書を書く方が実装するよりも苦手なことに長時間向き合わなければいけない、避けたい、と。

しかし、顧客は、設計書もないのに、なぜ実装に入ってしまうのかとプンプンです。そりゃそうだよなと思います。信頼関係がかなりあれば別ですが、基本は作る前に、どんなことやろうとしているかぐらいは情報が欲しいのものです。

顧客が怒るから設計書は書くべき、というのは話が逆転していて、そもそも役に立つ設計書を作っておけばいいのです。

私が考えるポイントは以下の通りです。

・決まっていないことは決まっていないと明確に書く。
・仮に決めておくが、実装時に変更になっても良いと割り切る。
・いくつかの選択肢があるのなら、その時点で決める必要はなく並行列記し、実装時に決めると言い切る。

このように、設計時に決めたものは鉄則で実装段階で設計変更はない、というのは私は良くないと思います。特に私のエリアであるITインフラについては、実際にインストールしたり使って見たりして初めてわかることが多いので、設計時にすべてを見通すのは不可能だからです。その中で、実装時は設計書を以下のように使います。

・設計書に、実装時に決定したことを追記したり修正したりする。
・最終的な設計書は、第三者が運用するときの手紙として完成させる。どういう思いで実装したのかを伝えるために作る。
・自分が読んで意味不明なものは作ってはいけない。

当初の設計段階ではわからなかったことや、新しい設計方針などが出てきた場合に、設計書を最新化するのは本当に必要です。なぜなら、運用時に第三者が設計書を見た時に食い違うとトラブルの原因になるためです。設計と実装は合わせて運用に引き継ぐべきで、運用に入ってからも、設計書のメンテナンスはした方が良いくらいです。

最終的に設計書がないシステムの場合、パラメータシートや手順書などしか残らないため、どうやって設計し構築したかを日本語でまとめた資料がない、と言う結果になります。最悪は、顧客もそれを当たり前と思って検収したりすると、運用時にも設計書がなく、営業時の提案資料ぐらいしか概要がわかるものがない、となってしまいます。

このように、設計書はむしろ自分や自分の会社のために作るものなのですが、技術者が実装しているときには頭の中に設計が入ってしまっているので、さぼりがちなテーマです。どんな小さなシステムを構築する時でも、メッセージとして設計書は作るべきだと思います。誰かに「このシステムの概略を知りたい」と言われたときに、設計書を渡すだけで済むのか、それとも現状のシステムにログインし事細かに確認しないとわからないのか。大きな差で、最終的には運用品質に跳ね返ってくるのが設計書です。

いくつかの現場で「なぜ設計書作らないで実装するかなあ」って思っていましたが、あらゆる場面でトラブルの原因になるので、ぜひ、作成しましょう。