懲りずにドキュメントについて考えてみた。。。

仕様書に記述するべき内容は、なんだろうか？
今回は、この事をテーマに考えたいと思う。

前回は、「仕様書」と「設計書」の違いについて考えてみたが、その時の「仕様書」に記述すべき事の回答(あくまでも個人的意見)として、仕様書は、顧客の要望(要件)を満たす内容(スペック)が記述されているドキュメントである。という事と、「どの様に満たすか(方法論)」は記述してはいけないと言う事。

例えば、「ブラウザーから対象データをCSVファイル形式でダウンロードする」といった要件があった場合、仕様書に記述すべき内容は、簡単(説明上不要な説明は省略して)に書くと以下の様な内容になるだろう。

1.○○は、画面の抽出項目に条件を入力い、「ダウンロード」ボタンを押す。
2.システムは、条件に合致するデータをCSV形式で作成し、ダウンロードパネルを表示する。
3.○○は、ダウンロード・パネルの「保存」ボタンを押す事により、クライアントＰＣに保存する。

上記内容は、全て記述しなければならない内容であるが、以下の２つのキーワードは特に大事になる。
・2の「ダウンロードパネルを表示する」という記述と、
・3の「ダウンロード・パネルの保存ボタンを押す事により」という記述である。

当たり前のように聞こえるが、仕様の一番の”キモ”は、この文章(キーワード)にある。
理由は簡単で、キーワードをはずした文章を作成してみれば一目瞭然である。

キーワードをはずした文章

1.○○は、画面の抽出項目に条件を入力い、「ダウンロード」ボタンを押す。
2.システムは、条件に合致するデータをCSV形式で作成し、クライアントＰＣに保存する。

まるで、意味が違ってくる事に気づいただろうか。
この仕様書をみたユーザーは、ダウンロードボタンを押す事により、クライアントＰＣにダウンロードが完了すると思うのである。

仕様書とは、何をどうすれば顧客の要望が満たされるのかを記述し、顧客はそれを見る事により、システムの仕様に対して「ＯＫ」なのか「ＮＧ」なのかを意思表示するのである。

当たり前の事だが、仕様(書)が「(上記の様に)はっきりしていない」システムは、直ぐに手直しが入る。
理由は、ユーザーからの(ユーザーと開発者の意思の疎通のずれによる)変更が頻発するためだ。

また、仕様(書)が、”しっかりしていない”システムは、別の問題も誘発する。
開発者は、その場では”どう動くか”を理解しているが、後になると細かい動きまでは覚えていないのである。
この問題は、保守時はもちろん、開発時にも十分発生しえる問題である。
例題では、ダウンロード・パネルの単純な動作１つを取り上げているが、実システムの全ての細かな仕様を覚えられる人はいないのだから。。。

大事なので、もう一度言う。仕様書は、顧客の要件を満たす内容が記述されているドキュメントである。
決して、内容に漏れが在ってはいけない。
また、仕様書には「どの様に満たすか(方法論)」は、一切不要なのである。

今回は、”のたまわる”ついでに、言い切った書き方にしてみました。。。(^^;)

最後に…これは、あくまでも個人的意見ですので、他の人の意見が聞けると、うれしーなぁ … ＾＾