YU2TA7KA's BLOG

派生開発、組み込み開発周りのこと。

ボロボロな技術仕様書から一部有用な技術仕様書を作成する

問題概要

技術仕様書 *1(以下、仕様書)の作成担当者からボロボロな仕様書が提出されました。

全体の構成が支離滅裂で突然何かの事柄に言及しており、全体像の見えない仕様書です。なぜ、全体像の見えない仕様書になったのか。それは、実装→仕様書への日本語訳、という順番で仕様書を作成しているためです。つまり、提出された仕様書は、実装の変更内容を個別に記載しているだけです。そのため、○○という機能を実現するためにAとBを変更する、というような記載はありません。Aに対して☓☓な変更をしました、という文が羅列されただけの仕様書になります。
この仕様書では、1ヶ月後には誰も参照しない無駄な仕様書になってしまいます。

対策

そこで、仕様書のポイントを抽出し、表や図でそのポイントを作成者と合意する、という対策をとってみました。
一般的に提出された仕様書全てをレビュー/修正することは時間的に困難と考えられます。そこで、仕様書のポイントを、提出された仕様書、作成者への口頭ヒアリング、作成者への文書でのQ&A、により抽出します。そして、そこから得られた情報から仕様書のポイントを抽出します。次に、そのポイントを表や図にして、作成者と認識合わせをします。認識が合えば、仕様書に追記して完了です。これで、ボロボロな技術仕様書から一部有用な技術仕様書を作成することができます。

f:id:yuji-tanaak:20180224154634p:plain
ボロボロな技術仕様書から一部有用な技術仕様書を作成するフロー図

表や図の使い方観点

調べればUML関連などたくさん出てきそうですが、ひとまず私の考えを示します。

表の使い方

条件マトリクスを作成する。ポイントとなる制御に対して、発生する条件を網羅し、各条件の制御をセルに示します。これにより、どのような制御パターンがあるか一覧することができます。また、制御パターンの考慮漏れや仕様上発生しないパターンの発見が期待できます。
f:id:yuji-tanaak:20180224153912p:plain

図の使い方

制御フロー図を作成する。ポイントとなる制御に対して、制御の順番を表現します。これにより、どのような順番で条件判断をするかが可視化され、制御対象の全体像を把握することができます。



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