こんにちは。
キャスレーコンサルティングIT(インテグレーションテック)部の高橋です。
今回は、「詳細設計書の書き方」と「記載時に心がけるべきこと」についてお話ししようと思います。
詳細設計書とは？
詳細設計とは、基本設計で決められた動きを「どうやって実現するか？」を説明した資料です。
そもそもシステム開発のライフサイクルは
要件定義→設計→製造→テスト→納品となっており、
設計フェーズは、要件定義と開発の間のフェーズとなります。
また、ひとことで設計といっても、基本設計、詳細設計に分けて設計されます。
基本設計は大まかな設計、詳細設計は細かい設計だと思っている人がいますが、それは誤りです。
基本設計と詳細設計は以下の点で異なります。
基本設計：システムを外から見たときどういう動きをするかを決めるもの
詳細設計：基本設計で決められた動きを、どうやって実現するかを決めるもの
また、仕様書と設計書についても以下のような違いがあります。
仕様書：何をつくるのかについて説明した資料
設計書：システムの作り方(どう作るのか)について説明した資料
更に詳しく説明すると、 仕様書には「結果」が書かれており、設計書には「過程」が書かれています。
仕様書はそれだけを見ても作れませんが、設計書はそれだけ見れば作れます。
仕様書は技術的なことを知らなくても作れる場合もありますが、設計書は技術的なことを知らないと作れません。
つまり、要件定義フェーズや基本設計フェーズで、
お客さまと一緒になって作り上げるのが仕様書
詳細設計フェーズで作るのが設計書
です。
ただし、便宜上、
要件定義フェーズでの成果物を要件定義書
基本設計フェーズでの成果物を基本設計書
と呼びます。
そして、詳細設計フェーズでの成果物を詳細設計書と呼びます。
詳細設計書を書く際のコツ
ここからは、詳細設計書を書く上で心がけた方が良いことを書いておきます。
なお、記載するコツはあくまで個人的なものなので参考程度にとどめ、
プロジェクトの内容や見栄えなども考慮して試行錯誤してみて下さい。
・章立てをする
①章の見出しだけをまず書いてみましょう。そうすることで、何を書くべきかがはっきりします。
②本文の各章の冒頭に、「本章ではXXの仕様について記載する」と書いておくと、
読み手にとって章の目的がわかりやすいと思います。
・全体→詳細の順で記載する
①まずは全体像を記載し、そのうえで詳細を掘り下げる書き方をしてみましょう。
そうすることで、読み手が全体像と詳細を把握しやすくなります。
・一文をなるべく短くしたり、箇条書きする
①なるべく簡潔な言葉で記載しましょう。誤解を生むリスクが減らせます。
②できれば2行以内で説明文が書かれているのが望ましいです。
それ以上になる場合は、文章を分解したり、構造が複雑化していないか見直してみましょう。
・図や表を使う
①複雑な条件や全体像を文字だけで伝えないこと。
図や表を適切に用いて直感的に理解できるように工夫しましょう。
・インデント（字下げ）を揃える
①読み手に対して文章構成を視覚的に理解してもらうため、インデント（字下げ）を適切に使います。
・主語や用語、表記を統一する
①設計書において、通常主語として描かれるのは「システム」か「ユーザー」が多いです。
同じ設計書の中で主語がコロコロと変わると、読み手が混乱するので統一して記載しましょう。
②同じ機能や同じ概念は、統一した用語を使いましょう。
同じ内容を別の用語で記載しないようにしてください。
③設計書の最後に用語集をつけると良いかもしれません。
④略語についても用語集に記載するか、もしくは初出時に
「Ruby on Rails（以下、RoRと記載）」のように記載しましょう。
⑤表記についても「サーバ」と「サーバー」など、表記ゆれがないように統一しましょう。
⑥文末についても「です・ます」調と「だ・である」調を統一して記載しましょう。
・記載粒度の認識を統一する
①基本設計書と詳細設計書で、どちらに何をどこまで書くをきちんと分けましょう。
②メンテナンスが追い付かなくなるので、必要以上に細かく書きすぎないようにしましょう。
・章立ての記載を統一する
①１．XXX
１．１．XXX
のように、数字の前半角、インデント、章番号の振り方などについて詳細を決めておきましょう。
・変更履歴の記載について統一する
①変更履歴が複数になった場合の色分けや、いつの変更履歴まで色分けして残すかなど、
また、世代の異なる変更箇所について色分けをするのか否かについても詳細を決めておきましょう。
以上の事をガイダンスとしてまとめ、参画メンバーが見られるようにしておくと
メンバーが増えた際や、交代の際に説明がスムーズにできると思います。
さいごに
というわけで、今回は詳細設計書の役割と書き方のコツについてお話ししました。
業務では、プロジェクト毎に雛型や記載項目がある程度決まっていることが多いので、
書き方についてあまり意識したことがない方も多いかもしれません。
ですが、「設計書は他の人が見るものである」という点を意識するだけでも、
工夫出来る箇所が見つかるのではないでしょうか？
慣れないうちは中々書くのが難しい設計書ですが、ここに記載したコツを元に
より読みやすい設計書を作ってみて下さい！
最後までお読みいただき、ありがとうございました。
