設計書の記載内容について

Question

いつもお世話になっております。

システム開発を行う中で、アジャイル開発を行い、最終的に基本設計書を起こしています。
開発サイクルが早いため、詳細設計書まで書ききれていません。

一度、開発プロセスを見直し、詳細設計書を記載したいと考えています。

APIを開発しAPI設計書は作成しているのですが、
APIの内部設計までは制作できておりません。
私の会社では、サーバーサイドの開発とクライアントサイドの開発が、
遠距離で別れているため、シーケンス図、API設計書、画面設計書が
どうしても中心になってしまっております。

ソース上にコメントを残しているのですが、それでも、これじゃまずいとおもい現在に至ります。

テーブル設計書しかり、ドキュメントが追いついて来ない場合が多々あります。
それがその状況であまり必要でないため、後回しになってしまっているためだと思いますが、
ドキュメントを起こす手間が否めません。これを見直すために、開発プロセスを見直すのですが、
ドキュメント作成に手間がかかりすぎて、開発があまりにも遅くなるのもどうかと思ってしまいます…。

皆様にご教授頂きたいのですが、

1. APIの内部設計書の内容・精度
2. 設計書のドキュメントのおすすめ

(私は、Excelと、WebサービスのCacooなどを利用していますが、Excelの内容が悪いのか手間です)

上記、2点をご教授いただけないでしょうか。

よろしくお願い致します。

Answer 1

そもそもなぜ詳細設計書を作成したいと思うようになったんですか？
シーケンス図、API設計書、画面設計書が揃っているのであれば、実装はできると思います。

僕が詳細設計が必要だと思う時はバッチ処理ですね。
画面は画面設計書があれば何となくイメージつきますが、
バッチは概要説明とある程度の処理内容を記載しないとプログラマに意図が伝わりにくいです。

画面設計書の粒度にもよりますが、僕は大まかに以下の情報はあるべきだと思っています。

• 画面のURL（実装者に自由に決めさせるのは好みじゃありません）
• 画面項目の説明（カンマ区切り、yyyy/MM/dd、少数第二位で四捨五入、初期値など）
• 基本的な入力チェック（必須、桁数、正規表現など）
• 業務的なチェック（パスワード変更が２ヶ月行われてなければ、パスワード変更を促すなど）
• 一覧表示があるのであれば、初期の並び順
• 画面項目とDBのマッピング（取得も登録・更新も）
• 画面に表示する全てのメッセージの内容（ここも実装者に決めさせるのは好みじゃありません）
• 全てのリンクやボタンの説明（どのテーブルに登録して、どこに遷移するぐらいのレベル）

APIの内部設計書の内容・精度

• １回の処理で複数通信するのであればフローが分かるもの（アクセストークンを取得してからなど）
• INとOUT（コード系は全てのコードの説明も。例えば処理結果の「成功」や「失敗」など）
• URL
• RESTであればHTTPメソッド
• APIの結果毎の振る舞いは、画面設計書やバッチ設計書に書く（呼び出し元）

設計書のドキュメントのおすすめ

結局は僕もExcelで書いてます。

• みんな慣れている
• お客様の環境にもだいたいOfficeの環境はある（PDFで渡すかもしれませんが）
• マクロで自動化などもできる

画面ワイヤーはCacooなどを使った方がいいかもしれませんね。
Excelで画面のイメージを書くのは中々面倒くさいですし。
Excelは表計算ソフトなので、ドキュメント作成の否定派は多いですが、
生産性は結局ツールの「慣れ」が占める割合が大きいのと、
ある程度誰でも使えるものという基準でいいと思います。
しょせんはドキュメントです。

Comments

[退会済みユーザー]

ご回答ありがとうございます。

> 詳細設計書を作成したいと思うようになったんですか？

詳細設計書がほしいと思った理由としましては、API仕様書を書いていた際に、
内部処理のイメージが付きづらいため、作成しようと思いました。

> 僕が詳細設計が必要だと思う時はバッチ処理ですね

この理由に近い気がします。

> 生産性は結局ツールの「慣れ」が占める割合が大きい

おっしゃる通りだと思います。
慣れてくるともう少し効率化できないか、ついつい考えてしまいました。

画面仕様書の精度のご教授ありがとうございました。