この記事は、「架空プロジェクトを通してシステム開発とドキュメント作成を体験してみる（2022 Late）」の記事の一部です。
詳細設計書の概要
詳細設計書は、基本設計に記述しなかった各機能の詳細な動きや設定情報を記述します。
どこに何を書くか？はプロジェクトや文化によって異なりますがウォーターフォール型のプロセスであれば要件定義書 + 基本設計書 + 詳細設計書で、開発を行うために必要な情報が揃っている必要があります。
| 項目 | 内容 |
|---|---|
| 作成目的 | 開発者が開発するための情報を提供する |
| 記述すべき内容 | 開発に必要な情報全て。機能概要、処理フロー、各種設定パラメータ、フォーマット等 |
| 作成タイミング | （詳細）設計 |
| 対象者 | 技術者 |
| ファイル形式 | パワーポイント、Excel、Word |
| 備考 | とにかく開発に必要な情報を提供すること |
一般的にはどうなのか？が気になる人は後半にある「一般的には（参考）」に先に目を通してもらったほうがいいかもしれません。
サンプルダウンロード
サンプルのダウンロードはこちらから。
作成してみる
では作成していきましょう。
作成方針・ポイント
概要でも書きましたが、詳細設計書までの書類で開発に必要となる情報の全てを記述しておく必要があるので、要件定義書、基本設計書の記述として足りない内容を記述していきます。
構成（目次）を考える
今回は下記のような項目を記述してみました。
一般的には基本設計で行う外部設計、内部設計といった内容に加え、実装に必要な情報を記述します。
- サーバ/アカウント情報
- 外部設計
- PC用画面
- スマホ用画面
- 画面のマークアップ
- バリデーションルール（フロント）と表示項目
- 送信ボタン押下時の処理
- スプレッドシートのデータ構造とレイアウト
- 内部設計
- APIの処理フロー
- APIの仕様
- バリデーションルール（バックエンド）と対応
各内容を記述する（サンプルの說明）
では、構成に従って作成したサンプルの内容について解説したいと思います。
表紙
目次
サーバ/アカウント情報
利用する各種サーバ情報やアカウント情報などを書いてます。
今回はサーバレス環境なのでアカウントとかURLが中心です。
外部設計：PC用画面
PC用の画面。Webベースの場合は詳細なレイアウトやデザインは別途デザイナーからテンプレートが提供されることが多いのであまり細かく決めない傾向にあるかな・・・とは思いますが、もちろん決めてもいいです。
外部設計：スマホ用画面
スマホ用の画面。こちらもデザイナーからデザインが提供されるので、それを適用することが多いですね。
外部設計：画面のマークアップ
どこまで細かくマークアップを指定するかはあるのですが、JavaScriptで制御する要素名、クラス名などはあらかじめ指定することが多いです。
外部設計：バリデーションルール（フロントエンド）と表示項目
バリデーションの有無、バリデーションルール、バリデーション時の挙動などを記述します。
なかなか文章で表現するの難しいです。。。
外部設計：送信ボタン押下時のフロント側処理
送信ボタンが押されたときの処理フローを記述しておきます。
ロジックなので内部設計？とも思ったのですが、フロント側の処理なので外部設計の一部としました。
外部設計：スプレッドシートのデータ構造およびレイアウト
スプレッドシートのレイアウトなどを記述します。データ構造は内部設計かな？とも思いますが、スプレッドシートの場合「帳票」的な位置づけかな？と思ったのでとりあえず外部設計に書きました。
DBなどを利用する場合は内部設計として、テーブル構造、ER図などを作成します。
内部設計：送信ボタン押下時のAPI側処理
内部設計：API仕様
APIの仕様を記述します。引数、戻り値など。
内部設計：バリデーションルール（バックエンド）と対応
バックエンドでもバリデーションを行うのでそのルールとエラー時の対応など記述します。
一般的には（参考）
実践ガイドブックでは？
残念ながら実践ガイドブックでは詳細設計書のテンプレートやサンプルは提供されていません。
仕方がないので政府系？ということで、みんな大好きIPAさんの資料を参考にさせてもらいましょう。
汎用的教育コンテンツ サンプルダウンロードサイトにある、4. ソフトウェア開発技法実践的演習教育コンテンツに、下記のようなコンテンツがあります。
設計方針が構造化ベースのものとオブジェクト指向ベースのものがあるようですが、オブジェクト指向ベースのものがいいかと（歴史を感じます）。
- ソフトウェア方式設計書（オブジェクト指向：良い例）01_ユースケース記述等.pdf
- ソフトウェア方式設計書（オブジェクト指向：良い例）02_シーケンス図.pdf
- ソフトウェア方式設計書（オブジェクト指向：良い例）03_クラス図等.pdf
一部抜粋して紹介してみます。
下記以外にも機能說明の記述方法など、（詳細の設計・仕様を記述する）いろいろな記述例が記載されているので参考になると思います。
逆に言えば、下記の３つを書くことが詳細設計ではありません（念の為）。
ユースケース図
誰が、何のためにどのシステム（機能）を使うのか？を表現するものです。
本コンテンツのサンプルには含まれていませんが、立場や権限の違う複数の利用者がいる場合などは、それを表現するために、よく使います。
シーケンス図
シーケンス図もよく書きます。最近ではMarkdownでも書けるようになってきました。
クラス図
個人的にはあまり記述はしませんが、継続開発を行っていくシステムの場合は書いたりします。
また、設計書ではないですが、下記のような要件定義がらみのものもあるようです。