SIerにおける設計書の重要性
こんにちは、リドルです。今日は、X上でバズっていた、なぜSIerではドキュメントを作って、
自社開発企業ではドキュメントを作らないのか、ということを説明したいと思います。ここで言うドキュメントっていうのは設計書のことなんですけれども、
確かにSIerではよく設計書を作りますよね。アプリだったら基本設計、詳細設計があって、
テスト使用書があって、単体テスト使用書とか、テストの結果を貼り付けるエビデンス。
インフラでも基本設計、詳細設計、パラメーターシート、ネットワーク構成図、
家電表、配線表、いっぱいありますよね。一方で、
自社開発だと、そういった類の設計書を作ることはあまりありません。この違いについて両方の企業で仕事をしたことがある、
リドルが回答したいと思います。これは簡単で、作る必要はないからってだけの話なんですけれども、
そもそもなぜSIerはそういった設計書を作るのでしょうか。これは単純に言うと、
もともとSIerってお客さんからこういうシステム作ってって言われて作るものなんですけど、その際に定期的にお客さん側から確認が入るんですね。
どうやって確認するかというと、各工程においてこういうものを作ってほしいというイメージが
一致しているかどうか。その一致しているかどうかは設計書をベースに判断されるという感じなんです。
そのため設計書を作らないとあいまいまでどうやって作るんだっけっていう確認がお互いに取れないので、最終的に出来上がったものが全然
期待と違うものになるっていうリスクがあるので、あいまいに設計書を作ってレビューして間違ってないですよねっていう感じで進めていっているというものになります。
自社開発企業の文書管理
またですね、SIerが作るシステムの場合は基本的に作って納品しておしまいっていう感じになるので、
その後のバージョンアップだったり更新という作業は別の費用をもらわない限りは発生しないんですよね。
要するに作りきりということです。そうなるとその時点の設計書っていうものはその時に作ったものを正確に反映しているので問題ないんですよ。
一方で自社開発企業の場合だと、例えばSaaSを作ってそこから収益を上げている会社を想定しますが、
最初に作ったシステムって本当にちっちゃいんですよね。 それは市場にどういうものがフィットするかわからないので、
まず最初に小さいものを作って、それが当たればもっといろんな機能を足していって、
ユーザーにより使ってもらえたりとか、ユーザーにより愛されるサービスにしていこうというような形でやっていくので、
最初に作った設計というのは徐々に形を変えていったり、何だったら丸っと作り直すレベルで変わることも珍しくありません。
そう考えると最初に作ったタイミングで設計書を一緒に作ってしまうと、設計書の更新も必要になりますし、
またサービス自体がすぐクローズする場合って、設計書を作ったところで何の意味もなくなっちゃうんですよね。
そう考えるとサービスの成長とともにだんだん変わっていくものであるにもかかわらず、設計書という全然変わらないもの、
もちろん更新すれば変わっていきますけど、そちらにも更新コストがかかるわけで、
ってなってくると、別にあんまり必要ないよねといったことが挙げられます。
またそもそもですね、社会付き業でサービスを作る際の普通の流れとしては、
プランナーとかPDMとか企画と呼ばれる人がまず仕様書というものを作ります。
こういう機能を足したい、この機能をこう変えたい、みたいなことを書いてあるすごい詳しいドキュメントですね。
これは設計書ではないです。
これをベースに、例えばフロントエンドだったり、モバイルの修正がある場合、追加がある場合は、
Figmaのようなデザインツールでこういう画面にしたいです、みたいなことを認識合わせます。
今挙げたような仕様書とFigmaに関しては、サービスの今の状態を正確に表すものなので定期更新していきます。
設計とドキュメントの役割
なので育てるドキュメントですね。
そこから先に実際にそれを実装しようというフェーズになると、ソフトウェアエンジニアの出番でしかないので、
PDMとかデザイナーとか企画というメンバーは一切そちらに関しては関与しません。
もともとソフトウェアエンジニア出身のPDMとかだったらもしかしたら見るかもしれないですけども、基本的には見ません。
そうなるとエンジニアの中だけでコミュニケーションが取れれば良くなるので、
カッチリとしたドキュメントを作る必要はなくて、例えばインフラであればIACのコードだったり、
Kubernetesのマニフェストさえあればなんとなくやってることがわかるし、
システムが大きくなってきてよくわかんないときはシステムのネットワークの構成図みたいなものを書いて運用することはありますけど、
それ以上に細かいもの、パラメータシートとかは作らないです。
IACのコードがあればパラメータシートとほぼ同じものなので二重管理になるとややこしいですし、管理コストも増えますしね。
またバックエンドだったりフロントエンドっていったものに関しても基本的には通信をする際のオープンAPIのスキーマとか
プロトバフとかグラフQLのスキーマみたいなものがあればどういう通信をしているかをそれを見れば一発でわかりますし、
バックエンド側の中のコードも読んでしまえば、このAPIはこういうふうにアクセスしてデータベースに問い合わせるんだ。
データベースにどういうデータが入っているのかはスキーマを見ればいいのでそれでわかりますよね。
たまにわからないものとして、すごい複雑なシーケンスを辿るような処理の場合、
例えば複数のAPIを叩いて初めて処理が完了するようなものの場合に関してはシーケンス図を作って管理することはあります。
ただやっぱりそれが正しく更新されないこともあるので、最近ではもうコードをベースにしてAIに都度生成してもらうって方がいいかもしれませんね。
フロントエンドだったりモバイルの場合でも基本的にはFigmaとかのデザインツールの方に完成形のデザインがあるので基本的にはそちらがベースになります。
それ以外の設計に関しては基本的にコードを見ましょうって感じが多いですかね。
こちらもどんどん変わっていくものなので基本的にドキュメントで管理することはありません。
ただですね、ADRというアーキテクチャーの決定をログに残そうというような考え方がありまして、
なぜGoogleクラウドを選んだのか、AWSじゃなくとか、なんでこういうアーキテクチャーにしたんだろうっていう私たちがその決断に至った理由みたいなものに関しては
どこかに残しておかないと次回以降あれ実はAWSでいいんじゃねみたいな話ができた時に
いや実は過去の一発でっていう説明ができなくなってしまうので、そういったものはGitHubで管理するチーム結構あります。
なのでアーキテクチャーディシジョンレコードですかね。これについては管理しますし、またAPIの新規の作成だったり更新、
またクライアントとのいろんな連携の際に複雑になりそうな場合は、私が参加してたチームだとGitHubのディスカッションみたいなところで
今回はこういう設計でいきましょうみたいなテンポラリーのドキュメントを作って認識合わせをした上で実装するということをやっていました。
ただそこのドキュメントについてはその瞬間に利用するもので、終わったら別に更新しないものになりますがね。
どっちかっていうとこれを決めるのにいろんな設計を考えてどれにしようかなという話なので、最終的に決まったものは
コードを見ればいいよねっていう感じが多いですね。 まとめるとSIRでドキュメントを作る理由はお客様との認識合わせのため
でいうのと納品をするのでその瞬間のことが正しく設計書に落とし込みからということでした。
またですね自社企業の場合はそもそも自分たちがどんどんどんどん システムをアップデートしていったり改善していったりするのでそこにドキュメントというものが相性が
悪いということと、あとコードベースを見れば最悪判断できるのでなくても問題ないといったところでした。
そういったような召喚集の違いがドキュメントを作る作らない問題の原生になっているかなと
どちらも働いた経験として思います。 このポッドキャストはハッシュタグいるITで皆様からのコメントやご意見募集しております。
また動画やエピソードの概要欄から Googleフォームのリンクもありますのでそちらからのご意見ご感想もいただけると大変嬉しいです。
ありがとうございました。
