2019年12月03日

仕様書には何を書くべきなのか


初めての方はこちらを「はじめに
全ての記事は「メニュー」にまとまっています

前回の記事「外注の形態と必要な能力」の最後の方で、「仕様書に細大漏らさず全ての挙動が書かれているのは当たり前の事です」と書きましたが、それがどの様な意味なのか、もう少し詳細に述べてみたいと思います。

何の為に仕様書を書くのか?


そもそも仕様書とは何でしょうか?何の為に書くのでしょうか?
答えは簡単です。「作る為」です。
より厳密に言えば「作るべきものを規定する」という事です。仕様書で「白」と書かれていれば「白」に作られますし、「黒」と書かれていれば「黒」に作られます。
当たり前の話です。

なぜこんな事をわざわざ言い出すのかと言えば、そうなっていない例が多いからです。
良くあるパターンは「プレゼン資料」になっているパターンです。「作る為」に書くわけですから、読む対象は「作る人」です。つまり設計したり、製造したりする人がこの文書を読んで、それに従って作る訳です。ところがそうならずに、上司やら営業やら諸々の関係者に対するレビュー(説明)の資料になってしまっているのです。ですから画面のイメージを貼り付けただけのような「素人でも分かる」程度のものになってしまっていて、実際に作る技術者からすれば、まるで内容が足りないものになってしまっています。

仕様書というのは英語で言えば「specification」です。「詳細」という事です。イメージや雰囲気を伝えるような類のものではありません。

記述するレベル


では、画面のイメージを貼っただけというのは論外だとしても、実際にどの様なレベルまで記述する必要があるのでしょうか。
これも答えは簡単です。「書かれていないものはどうなるか分からない」という事です。つまりどうなってしまっても構わないという内容以外は「全て書かなければならない」という事です。
当然書かなければならない事は膨大です。それ以前に検討しなければならない事が膨大です。ですから「仕様とはルール」で述べた通り、論理で考えない限りは考えきれません。一つ一つの仕様を個別に考えて行くのは不可能です。

良く記述が抜ける例としてエラーのパターンがあります。
うまく行くパターンしか書いて無く、エラーになるパターンについては何も記述されていないのです。例えば「ESCキーでキャンセル、リターンキーで確定」と書かれてはいても、「その他のキー」はどうなるのかはどこにも書かれていないのです。「その他のキー」の挙動はいつも同じならば、どこかに共通の仕様として一つ書かれていればそれで十分ですが、どこにも書かれていないのでは「どうなるか分からない」事になります。

記述する範囲


あと、これも「どこまでが仕様の範囲か」で既に述べた事なのですが、ワークファイルに関してとか性能に関してなどの非機能的な項目についても仕様書に記述するべきです。厳密には「仕様書」という文書の分類では無くても構いませんが、仕様を考えるというタイミングで、「作るべきものを規定する」文書の中に入っている必要があります。
先程も書いた様に「書かれていないものはどうなるか分からない」のです。速度やメモリー消費が「どうなってしまっても構わない」のでしょうか?動かしてみて初めて「こうなりました」でいいのでしょうか?それで構わないというならば記述する必要はありません。しかし普通そんな事はないはずです。

質を向上させるには


仕様というのは「大枠を考えて、あと細かいところは実際の担当者が作る時に決める」などという甘いものではありません。そのように担当者に依存する部分が多ければ多い程、「外注の形態と必要な能力」で述べた様に外注に出すのが難しくなります。
この事は、実は仕様書の質を自分で判断する基準にもなります。
つまり「この仕様書は○○(目の前の担当者)ではなく、全然面識のない人間に渡した時に期待通りの物ができあがるだろうか?」と自問するのです。そうすると、目の前の人間とはいつも会話しているので結構ラフに書いていたり、実は組織内で暗黙のうちに共有されている知見が意外にあったり、という事に気が付きます。そうやって気が付いた事を少しずつ明確に記述する様に直していけば自ずと質が上がっていく事になります。

記事一覧


  • メニュー
    全ての記事が分類整理され、選択的にアクセスするためのトップ
  • 用語集
    ブログ内で使用されている専門用語や独自の用語などを簡単に説明したものです。


記事を広める




posted by 善 at 19:58 | Comment(0) | 仕様 | このブログの読者になる | 更新情報をチェックする
この記事へのコメント
コメントを書く
お名前:

メールアドレス:

ホームページアドレス:

コメント:

※ブログオーナーが承認したコメントのみ表示されます。