詳細設計書の書き方の例を紹介！

こんにちは！

ITエンジニア・webディレクター・webデザイナーなどのIT人材の自立・キャリアを支援するITプロパートナーズのCTOの柳澤（やなぎさわ）です。

弊社は、独立精神旺盛な優秀なエンジニアの方々の独立・起業サポートや、フリーランス支援を行っている会社です。

こちらのジョブウィズでは、企業の新規事業開発担当者の方や、システム開発責任者の方、事業責任者の方達に向けて、事業開発のコツや、自社プロダクトやWebサービスを立ち上げる際にポイントや注意点について、弊社ノウハウを包み隠さずにお伝えしています。

今回は、詳細設計書について書きます。

早速本題を見ていきましょう。

詳細設計書とは

システム開発において、必ず行う工程の1つに詳細設計書の作成があり、システムの詳細をまとめた資料のことをいいます。

この資料を参考に、プログラマの方はシステム開発を行っていきます。

要件定義、基本設計はクライアントに用意した設計書ですが、詳細設計書はプログラマに向けて書かれています。

詳細設計を書く工程ですが、システム開発の基本的な流れは「設計」「プログラミング」「テスト」の3つに大きく分けることができます。

この設計の中の1つに、「詳細設計」があります。

工程の中で、どの作業を基本設計で進めるか詳細設計で進めるかはプロジェクトや企業によって変わってくる場合もあります。

詳細設計書の目的って？

詳細設計書を作成する目的、それは詳細設計が内部設計と呼ばれるように基本設計で定義したシステム概要の仕様を、どのようにすれば形にしていくことができるのか明記することにあります。

良いとされる詳細設計書には、読み手によって解釈が分かれるという曖昧な表現はしておらず、詳細にプログラム仕様が書き込まれていることによりプログラマが頭を悩ませずコーティングすることが可能になっています。

それには、「必要モジュール」、「処理ロジック」、「用意する変数」、「SQL文」といったプログラミングに必要な情報をあますことなく記載する必要があります。

あくまで重要なのは、どういったフォーマットかではなくどういった情報が書いてあるかになります。

詳細設計書の書き方の例を紹介

詳細設計書の書き方ですが、企業やプロジェクトによって書き込む定義は変わってきます。

なので、ここでは書くべき項目について明記します。

しかし、最低限のルールとして基本設計書の定義した仕様を詳細設計書でプログラム仕様にまとめあげる必要があります。

また、両設計書間で必ず矛盾が生まれないようにしましょう。

詳細設計書に書くべき項目と内容

・システム開発について

企業やプロジェクトにより呼び名は変わってきますが、ソフトウェアの開発からクライアント企業でシステムが動くまでの際に必要となる、詳細設計書の内容例をご紹介したいと思います。

システム開発に於いて、「インフラ」、「ネットワーク」、「ソフトウェア」といった内容を書いておく必要があります。

インフラ設計について

インフラ設計の項目では、クライアントなど専門家が見なくても設定の内容が把握できるよう記載されている必要があります。

企業やプロジェクトによっては、詳細設計書ではなく「セットアップ手順書」、「SG仕様書」と呼ばれることもあります。

新しいシステムを、誰もが手順通りにセットアップできるように書かれているのが望ましいでしょう。

ネットワーク設計について

ネットワーク設計は、LANかWANによっても作成する設計書の内容は変わってきます。基本的に書く内容は以下の項目通りです。ネットワーク構成図

• （論理設計図/物理設計図）
• ネットワーク機器一覧
• IPアドレス管理表
• ネットワーク機器設定表
• ネットワーク信頼性確保方式
• ネットワーク帯域一覧・帯域確保方針

このように、ネットワーク設計には各機器がネットワーク内に存在するための情報全て含まれていなくてはいけません。

ネットワーク内の機器の名称やIPアドレスの番号は必ず記載しておく必要があります。

ソフトウェアについて

ソフトウェアでは、完成しているプログラムを動作させるのに必要な情報を記載しておく必要があります。

どこにプログラムを配置し、こちらの想定通りにプログラムを動かすためにどういった設定内容を指示すればいいか記載しておきます。

内容を書く際は、作業者が分かりやすいよう箇条書きにするなど工夫するようにしましょう。

データベースについて

データベースでは、物理設計と呼ばれことが多い工程が詳細設計になります。

データベースにあるユーザー、スキーマー、テーブル、ビューなど全ての設計を具体的にし、プログラム内で仕様される名称を定義します。

このデータベース詳細設計書に書かれている内容に沿い、データベースを作りあげることが必要です。

そのため、全ての項目とその内容をしっかりと記載していかなくてはいけません。

項目を上げていきましたが、詳細設計書を作成するときのコツについて触れていきます

詳細設計書を書くときのコツって？

詳細設計書を書くときのコツ、何を意識すればいいのか？

詳細設計書の書き方で、もっと重要なのは次の工程へと確実に指示を繋げることです。

書き方に配慮が足りず、質問が出てしまったり情報が正しく伝わっていなかったりした場合、それは良い詳細設計書とはいえません。

もちろん、情報や指示が漏れなく記載してある詳細設計書というのは非常に難しく、皆無に近いというのが本当のところです。

しかし、少し意識するだけで改善することもできます。

主語と目的語を記載する

日本語は省略しても伝わりやすい言語のため、主語が抜けている詳細設計書を作成してしまう方も多いかと思います。

口頭ならばそれで問題ありませんが、文字となるとそれでは上手く伝わらない可能性が高いです。

また、主語がない場合は書いた本人しか内容が理解できない場合が多いため、質問や混乱から工程が遅れてしまうことも考えられます。

これは目的語にも同じことがいえて、しっかりと主語と目的語を記載し読み手が誤解しない内容にしましょう。

箇条書きにするなど工夫をし読みやすくする

詳細設計書となると、記載されている文章量も多く1つの項目が非常に長くなってしまいがちになります。

その結果、ごちゃごちゃした内容になってしまい読みにくいケースになりがち。

そのため、箇条書きを使うなど工夫をし、読みやすい文章になるよう意識することが大切です。

他にも、条件判定などでは表を使った方が一目で分かりやすい場合が多いと思います。

それ以外にも、設計書だからといって文章だけに拘る必要もありません。

数式などで書いた方が見やすい場合は数式にするなど、書く内容に適した文章になるようにしましょう。

記載内容が多すぎる場合もある

ここまでは、記載内容をしっかりと書く必要があると伝えてきました。

しかし、記載内容をしっかり書くということは決して「文章量が多い」ということではありません。

反対に、内容が多すぎて邪魔になってしまう場合もあります。例えば、コードレベルまで記載されているとプログラマの自由度がなくなってしまいます。

その結果、問題が発生したとしても設計書と差異が発生してしまうためプログラマ側が変えることができないといったケースが多いです。

また、テストが行われていないためコーディング時に初めて仕様の矛盾に気づき、設計書の見直しが必要になってしまうといったこともあります。

こういったケースから、大切なのは文章量ではなく詳細設計書の「内容（質）」であるといえます。

上下横の関係を追えるようにする

全てのことにいえますが、仕様書を読んだとき横だけではなく上下の関係もしっかりと追えるようにする必要があります。

そうしないと、読んでも理解できないということになりなぜそれが必要なのか理解されないまま工程が進んでしまい、解釈の間違いからトラブルが発生してしまうことも考えられます。

また、全てを追えるということは全体の流れを理解しやすくもなります。

1人で全て行うならいいですが、チームで行う場合など全体の流れをある程度把握できた方がスムーズに進む場合も多いはずです。

まとめ

いかがでしたでしょうか？

詳細設計書は、上流工程から下流工程へ伝えるべき重要な情報が記載されている必要があり、またそれをしっかりと伝えていくためには書き方の工夫も必要になってきます。

成果物の品質を高めるためにも、詳細設計書の書き方に注意をしていきましょう。

この記事が皆様のお役に立てば幸いです。