設計工程について、自分なりにまとめてみました。

オフショアでベトナムに設計書を出したりしていたので、日本人相手だけでなくベトナム人相手も想定した内容になっています。

言葉の定義

基本設計、外部設計、機能仕様

ユーザの観点から製品がどのように動くか記述する。それはどのように実装されるかは問題にしない。それは機能を話題としており、画面とか、メニューとか、ダイアログとかいったものの仕様を定める（joel on software)。

要は画面なり機能なりの振る舞いを定めている。ユーザ視点。どう作るか、ではなくてどう動くか。

詳細設計、内部設計、技術仕様

プログラムの内部の実装について記述する。それはデータ構造、関係データベースモデル、プログラミング言語や開発ツールの選択、アルゴリズムといったものを話題としている（joel on software)。

要は、データ構造なり処理の流れなり、プログラムの構造について定めている。
プログラマ視点。どう動くか、ではなくてどう作るか。

具体的に何を記載するか

joel on softwareをベースに、自分とメンバがやりやすいように手を入れた。

機能仕様

A. Background（背景）
何が問題なのか
何でこの修正が必要なのか

B. Purpose（目的）
この修正の目的は何か
この修正によって解決される問題は何か
どういう状態になれば完了なのか

C. Scope（範囲）
今回、何をやるのか

D. Out of scope（範囲外）
今回、何をやらないのか
（次フェーズでやる可能性があるのであれば書く
設計や実装に影響するので）

E. AsIs（現状）
現状の説明（画面のキャプチャー付きで問題を説明する）

F. ToBe（ゴール）
どういう状態になれば完了なのかを絵付きで説明する
期待される振る舞いについて説明する
（バリデーション、ダイアログ、メッセージ、エラーなどもここに記載）

技術仕様

A. Process flow（処理フロー）
処理の流れを図で説明する
入力、処理、出力をきちんと書く

B. Data definition, relate DB（DB周り）
テーブル定義に変更が入るのであれば、その説明
後は新機能であれば、DFDを書いて説明
挿入、更新、削除の処理があるのであれば、その条件や項目など
参照の場合も複雑になる場合は書く
（IDから1項目引っ張ってくるだけーとかであれば不要）

C. Validation（バリデーション）
必要なバリデーションについて説明

D. Error case（エラー）
エラーは二種類ある
システムエラーとプロセスエラー（ビジネスロジック起因）
主に、プロセスエラーについて書く
機能仕様のエラーと対応

E. 他に何か必要があれば、適宜

実際のところ

意外かもしれないが、ベトナムから一番要望が強くて、追加したときに効果も大きかったのが目的と背景。なぜこの機能が必要なのか、この機能がどう使われるのか。ここら辺をしっかりと書いておくと、逆に他が多少甘くても向こうから色々提案してくれる（こういう目的ならこういう実装の方がいいんじゃないかーとか）。

ちなみに、簡単な機能追加であれば機能仕様だけ投げればいける。複雑な機能の場合は技術仕様が必要（ベトナムの特徴として、全体を見るのが苦手というのがある。複雑な機能の場合、技術仕様がないと動くには動くが保守性が最悪なものが出来てきたりする。もちろん、別途コードレビューなどはおこなった方がいい）。

新規開発の場合、平行して運用設計が必要になる（ログどうするか、障害が起きたときどうするかなど）。別途書く、結構これを忘れる人が多い気がする（特に開発オンリーで保守運用の経験がない人）。

今後試してみたいこと、気になっていること

ペルソナをつくり、目的の部分などでその人が実際にどういう問題に直面し、どう困るかを設計書に盛り込みたい。わかりやすさの向上＆ユーモア。ユーモア重要。

海外では実際どのくらいの粒度の設計書が普通なのか、気になる。国や業種などにも寄るだろうけど、例えばある程度大手がインドに出す場合とか。ちなみに、joel on software でサンプルとして挙げられている仕様書はこれ。