photo credit: database plan via photopin (license)
ある日、プロジェクトのメンバーから「こんな設計書しか書けないクソリーダーの下で仕事をしたくない」「Excel方眼紙の最低な設計書」と陰で言われたことがありす。
設計については独学ながらいろいろ勉強し、工夫してきたつもりだっただけに、だいぶヘコみました。
ただ、これは設計書を根本的に見直す「転機」なのかもしれないと、ポジティブに考えることにしました。
１．Excel設計書の賛否
いろいろなサイトを見てみると、Excelを利用した設計書の記述では賛否あるようです。
特にExcel方眼紙に対するコメントは非常に多かったです。
そして自分の設計書もExcel方眼紙です！
Excel設計書・Excel方眼紙を「悪」としている記事を調べてみると２つの傾向がありました。
- Excelは方計算ツールなので設計書で利用するのはおかしい
- 記載内容が足らない、または多すぎる・細かすぎる
この２つの傾向をもとに、自分なりに設計書の「あり方」を考えてみることにします。
２．Excelは表計算ツールだけか？
「Excelは方計算ツールなので設計書で利用するのはおかしい」
正論ですが、このコメントは正直どうでもよいと感じました。
Excel＝表計算ツールという考えは少し視野が狭いのと、一番大切な「相手」を考えていないコメントだからです。
と言い切っていますが、自分も昔は同じ考えから「Visio」や「Word」ときには「Jude（現在のastah*）」を使って設計書を作ったことがあります。
しかし、そういった特殊なツールを利用した場合、お客様や委託先に資料を送ると「この資料は開けない！」と問い合わせや時にはクレームが来ます。
３．設計書は誰のものか？
設計書というのは、設計書を使ってレビューをしたり、設計書をもとに作業を指示するといった時、必ず「相手」がいます。
そのため設計書は「相手」も使えるツールであることが重要なのです。
また、ツールにライセンス費用が発生する場合はもっと注意が必要です。
自分たちはすでにライセンスを購入済みで余計な出費はないかもしれません。
しかし、「相手」はどうでしょうか？
ライセンスを持っていなければ購入が必要です。
それが発注元であればわざわざライセンスを買ってくれるでしょうか？
また、毎月もしくは毎年利用するのに費用が必要だった場合、保守フェーズに入った際も継続してライセンスを購入し続けるでしょうか？
便利だからという理由以外に、費用がかかるツールを利用する場合は、利用範囲や期間を明確にする必要があると思います。
４．設計書は誰が作成や編集をするのか？
次に気をつけなければいけないことは、設計書を改版したりコメントを記入する際、ツールを利用する「相手」とスキルレベルがあっていることが重要です。
例えば、身近にある「Microsoft Word」が意外と曲者なのです。
「Word」の使い方を熟知していないと、インデントをスペースで開けたり、途中で用紙の向きを変えるなど、ちょっと変わったことをやろうとするたびに「調べたり」「覚えたり」と時間がかかってしまいます。
そのため設計で使うツールを決める際には以下のようなルールを決めました。
- ツールが資料を共有する「相手」にも導入されていること
- ツールの利用するためのスキル習得が簡単もしくは習得済みであること
- ツールに継続的なライセンス費用が発生しないこと
このルールに該当することから、現在では設計で一番Excelの利用が多い状況になっています。
５．その設計書は行間ないですか？
昔、外部の委託先に開発をお願いした際、期待した機能が盛り込まれていなかったことがあります。
それもそのはず、自分が提示した設計書は「行間」が多く、（当たり前ですが）それを汲みとってもらえなかったのが原因でした。
委託先の担当者は要望の背景や全体の要件を理解している人だったため、こちらの考えを汲み取ってもらっていると思っていました。
しかし、実際に開発するメンバーは理解度の高い人以外が多く、「行間」は汲みとってもらえないのも当たり前だとその時知りました。
そういった教訓から、設計書の記載を見直し、できるだけ詳しく書くように心がけるようにしました。
つまり、設計書の水準を「仕様理解度が低い人」に合わせて記載したのです。
これが「良」設計書だと信じていました。
６．設計書の「量」より「質」とは？
「記載内容が足らない、または多すぎる」
今回の設計書の見直しで、「詳しすぎる詳細設計書」の記事に出会ったことで、実はただの自己満足であることを知りました。
そこで、この「詳しすぎる設計書」の何が「悪」なのかを考えてみると、以下の内容があげられます。
- コードレベルまで記載されていてプログラマの自由度がなくなってしまう
例：プログラムの部品化などロジックを変えてしまうと設計書と差異ができてしまう - コードレベルまで記載されているが検証（テスト）はしていない
例：コーディング時に仕様の矛盾に気づき設計書に記載したロジック見直しが必要 - 同じ内容がいろいろなところに書かれている
例：機能単位に記載しているため、同じような処理が複数の設計書にかかれており修正が発生すると仕様書のメンテナンスが大変になる - 設計者のスキルによってプログラムの出来が左右される
例：設計者のコーディング知識に左右されるため、設計者のプログラムスキルによって品質が影響される。
プログラムのステップレベルに近いところまで設計書を記述しても、実際にプログラムを書いているわけではありません。
その細かい設計書を提示し、プログラムを書くときには全く同じ、もしくはそれ以上の工数を書けてプログラムを作成する必要があります。
そういった重複している作業を増やすのではなく、コーディング規約やメッセージ規約など、プログラマの「質」を上げるための工夫が必要でした。
７．まとめ
共通的なツールとして利用できるExcelをベースとした設計書作成は賛否両論あるようですが、自分はまだしばらくは続けていこうと考えています。
その代わり設計書の「質」を上げるために、何ができるのか以下の内容を観点に今後精査していきたいと思います。
- 作成する必要のある資料、必要のない資料を整理する
- 記述する内容、記述しない内容を整理する
- 開発を委託する側としてどんな設計資料が必要か？
- 開発を依頼する側としてどんな設計資料が必要か？
- 運用をするにあたってどんな設計資料が必要か？
- 保守改修をするにあたってどんな設計資料が必要か？
１．Excelの設計書の問題は、Excelに設計書の妥当性を評価する機能がないことです。
・明らかに間違った設計であっても、Excelは、その設計の誤りを指摘してくれない。
・設計書の記載レベルについても、人が考えて、基準を決め、意識の統一を図る必要があり、仮に、その基準に則った記載ではない人がいても、Excelは、指摘してくれません。
２．同じソフトなのに、複数の資料を作れてしまうし、必要になってしまうこと。
同じソフトなら、コードは一つです。
同じコードなら、対応する設計も一つであるべきで、それをどのよう見せるかという部分は、ツールにやってほしいなと個人的には思いますよ。
勿論、作ったら、客に渡して、あとは放置、ひどいバグがあっても対応しないし、運用だってしないのであれば、Excelは、そこそこ使えるツールなのかなと思いますけどね。さくっと作って、渡せますからね。この場合でも、詳細設計書が必要になるなら、エクセルはないかな。
chronosさん コメントありがとう御座います！
プログラム構図などコードに近い設計工程になると確かに指摘の部分は大きですね。
ではもっと上流の機能設計レベルならどうか？をコメントを見ながら考えていました。結論からする、入力チェックなど重複した記述が複数の設計書（Excelファイル）に記載され、それぞれの設計書間で矛盾が発生することは想定できますね。では冗長的な記載をどうするか？など考える点が多く、これがベストというものを見つけるのは難しそうですね。
ちなみにchronosさんはどんな設計ツールを利用されていますか？今後の参考のためにも教えていただけると嬉しいです。
トレーサビリティを取らなければいけないような、厳密に整合性の担保が必要なものでは、Enterprise Architectを使う事が多いですね。
一方で、多少の差異に目を瞑る場合、Excelを使う事もありますね。
この場合でも、ER図は、ERMasterや、A5:SQL Mk-2などのツールを使って自動生成させるケースが少なからずありますね。
また、後者のケースでは、テスト実施中にもテスト合格の基準がぶれてる事があるので、単体テスト実施後に、単体テストで発見すべき不具合を修正したりなど、対応が後手に回ることが少なからずあるような気もします。
要件定義や基本設計に近い部分を記載している場合は、人数が少ない場合が多いので、記載レベルや記載内容の一致を図るのが容易であるって状態であるような気もします。
まぁ、これがベストだというものが仮に存在していたとして、それを見つけるのは難しそうですが結構多くのツールを連携させて使うようなものがベストになるのかなぁという気もします。
なるほどUMLツールを使用することで、クラス図などから整合性は取れやすくなりますね。
自分もUMLツール検証はしたことがあるのですが、設計以降の開発フェーズに入ると、メンテがされなくなり徐々に乖離していってしまうケースがあったので運用方法も課題だと感じました。これはExcelの設計書でも同じ事言えるので、「開発後の設計書のメンテ」もルール決めが必要そうですね。
ERMasterは自分も使っています、ER図もテーブル定義書もDDLも一貫して管理できるので重宝してます。
確かに、プロジェクトや設計に関わる人数で適材適所のツール選択が必要ですね。
ただ、人数が増えることでツールの利用スキルの差も出てきてくるのでいろいろ課題は多そうです。
いろいろと試行錯誤している中、勉強になるコメント頂いて非常にありがとう御座います。
くだらないブログですが今後もアドバイスなどコメントいただけると嬉しいです！
設計書といっても、二つの目的のドキュメントがあるかなとふと思いました。
1つ目は、お客様と合意をし、お客様に納品するドキュメントです。
この用途の場合、編集できるべきとは思いません。PDFで十分な気がします。
2つ目は、製造や保守の際に、自ら使うドキュメントです。
この用途では、高価なソフトを購入しなければいけないドキュメントでも構わないでしょう。要するに、お客様にソフトを買わせるという結果には、ならないはずです。
では、どちらにも当てはまるドキュメントはというと、２の用途と同じ作成方法で作成し、PDFなどに出力するというのが妥当なのかなと。
なるほどです！参考になります！！
頂いた情報をもとに何が設計者・開発者・顧客にとってベストなのか考えていきたいと思います。
また、整理出来たら記事書きたいと思います！
エクセルは改造しないとマジで使えないゴミ
特に文字が小さいステータスバー？あの下のやつ
あんなの見てると目が悪くなるぞ
あとはすんげ～見づらいワークシートタブ？
あれも数作ると何が何だか間違えやすくなるしなにより見づらい
しかもタブを複数選択するといろいろクリックしてももとになかなか戻らないクソ
仕様にイライラする しかもシートの保護とかいう機能がオフになりやがる ここも改造しねーとなんねー
つーかこんなポンコツ表計算ソフトじゃなくてなんか国産でいいのだせよなマジで
論外
そもそもドキュメントの共有時間（作成も含めて）にロスが多すぎる
担当者レベルへの周知にも時間がかかる
書式云々など無駄な管理が多い
そもそも
gitで差分管理もできない
論外
そもそもドキュメントの共有時間（作成も含めて）にロスが多すぎる
担当者レベルへの周知にも時間がかかる
書式云々など無駄な管理が多い
そもそも
gitで差分管理もできない
phpエラー出るぞ（・・・）