設計書の書き方

こんにちは。こんばんわ。

湘南オンライン開発担当のお猿です。

最近、詳細設計を書く機会がありましたので、今回は設計書について書いておこうと思います。

SES案件や持ち帰りの案件ですと色々な理由(後述)で設計書を書く必要がある場合があります。

が、毎度の事ながら

「どのテンプレ使おうか?」

「何処まで細かく書こうか?」

等で悩みます。

 

体感ですが、書く内容は現場によってかなり差が有ります。

その現場が設計書に対して何を求めているのかによります。

では現場で求めている設計書にはどんなものがあるでしょう?

求めてる設計書を確認する

簡単で良いよ!って軽くいわれた設計書

殆どの場合、お客様に「簡単で良いので出してくれ」と言われたため作成する場合です。

これは割と「いるの?」って思いますがこのパターンは結構多いです。

気合いを入れてもお客様はほぼ見ませんし、設計書に時間割くよりコーディングや打ち合わせに時間割いた方が効率が良いと考えて作成しない、もしくはアジャイル開発で別途管理を行っているパターンです。

まぁ本当に形だけの資料です。

打ち合わせ用

打ち合わせ資料の延長+ドキュメント要素がある感じですね。

私はこれが好きです。

が、結局後で見たとき分からないパターンが多いです。

この場合はロジックだったり構成要素だったりは最小限で良いです。

あくまで打ち合わせ用資料を兼ねる物なので、分かりやすさが1番大事です。

テスト用

以前上げた記事でV字モデルを覚えていますか?読んでない覚えてない方はこちらを読んでください。

設計は基本的にテストと結びつきます。このテストは品質保証の為の物です。

つまり、設計書があれば現物は無くてもテストすべき項目が分かります。

つまり無駄なテストを行わなくてすみます。

と言うと「設計書と合わせてテスト仕様書も書いてしまえば資料作成をまとめられて良い!」と思ってしまう方がいると困るので、補足しておきます。

設計は打ち合わせを重ねると変わって来ます。

ですので、先にテスト仕様書を作ってしまうと設計が変わる度にテスト仕様書も書き換えなくてはならなくなります。

 

これは本来の設計書のあるべき姿だとは思いますが、ここまで作ると中々に時間がかかります。

なので、時間を掛けない範囲でコレがあればテスト仕様書も作れる!って程度にするのがベストですね!

外注前提用

外注用に打ち合わせを出来る限り少ない回数で出来るようにする物です。

まぁこれも分かります。

打ち合わせ回数を減らせるくらい作り込む訳ですから、ドキュメントとして取って置く物としても便利です。

この場合はとにかく細かく細かく記載します。

そうしないと、質問がひっきりなしに来たり、質問用エクセルにビッシリと質問が書いてある物を渡されたり。

最悪、異なる性能の物がでてくる場合も。

これも分かりますが、ココまで来ると設計書の意義が多少変わってきている気もします。
また設計書を細かくし過ぎると、その設計書を元に作る方の自由度がかなり絞られるため、設計段階でのバグ等も仕様にあるから…といった理由で報告が上がらず、誰も気が付かないうちにリリースされてしまう事があります。

その為、結局のところ上手に設計を行い、コーダーとコミュニケーションを取りながら進めるので、その塩梅がとても難しくなります。

エビデンス用

上記の内容を全て含めたタイプのものです。

「含めるって…」と思うかもしれませんが、打ち合わせ用の資料を寄せ集めて、まとめたものです。

エビデンス⇒証拠ですので「お客様との打ち合わせはこのように決まりました。」といった証拠用で作成したものになります。

ソフトウェアの場合、手戻りが多いとそれだけコストがかかります。
それを回避する為に打ち合わせして、決まった内容を「エビデンス」として資料を残します。

「言った・言わない」のような不毛な揉め事を避ける為にもエビデンスは重要です。

 

が、こちらは大体、後出しになります。

考え方によっては打ち合わせするのに設計書が必要なので順番が逆になりますね。

設計書の記載内容

設計書はものによって、ものすごい時間がかかります。

その為、設計書への記載内容は目的に合わせた設計書を作らないと、無駄な作業が増えてしまう事があります。
その為、まずは設計書の用途を確認するのが良いです。

具体的な内容についてはまた後日記載したいと思います。

まとめ

設計書に決まりはないですが目的によって、記載内容が変わったり、かかる時間が増減したりします。

その為「何のための設計書か」をはっきりさせてから話を進めるようにしてください。

 

以上!!