プログラミング素人のはてなブログ

プログラミングも電気回路も専門外の技術屋の末端が勉強したことや作品をアウトプットするブログ。コードに間違いなど見つけられたら、気軽にコメントください。 C#、Python3、ラズパイなど。

仕様書を作るということ

誰かに何かを依頼するときにはその「指示」が必要です。

ここで私がイメージしている「指示」は必ずしも文書になってなくても良いですが、
・作業指示書
・ソフトウェアの要求(または要件・制御)仕様書
といったものです。

このときにいつも悩むのが、どのぐらいの粒度でどこまで深く記述するか?ということです。
例えば以下のような仕様を考えるとします。

プリンタのトナーが無くなったら知らせてほしい。

相手がプリンタを使い慣れている人で会社の在籍期間が長いなら、まさに上記のように伝えればOKでしょう。
しかしこれが新人であったり、そもそもプリンタをほとんど使ったことが無かったりした場合はどうなるでしょう?

私なら少なくとも、
「トナーがなくなったらプリンタの画面に表示が出るので、そのときに私を呼んででほしい。私が捕まらなかったらMailを入れておいてください。」
のように指示をします。

これを
・トナーがなくなったら私に連絡する
・トナーがなくなった状態というのは、プリンタの画面に表示が出ている状態である
・連絡方法は直接呼ぶか、Mailを入れる
のように記述するのが、仕様書(作業指示書)となります。

すると、実は問題が起きます。
この仕様に従うと「プリンタのトナーが無くなった」という状態が発生し、プリント作業が中断されてしまいます。
ですから本来は「プリンタのトナーが無くなりそうになったら」とすべきなのです。
しかしこれでいいかというと、これもダメで、「表示は出ていないけど画像がかすれ始めた」という問題も起きうるのです。
また、プリンタによっては表示画面が無く「赤いLEDが点滅する」ものもあります。

指示を細かくすればするほど、このような「抜け漏れ」が発生するという矛盾が生じる気がするのです。

反対に、目的を主として仕様を指示しておくと、
・プリントに問題が起きそうなら連絡して
・問題とは、画像不良がでること、プリントが止まること、その他の不良が出ること

要求と理由をセットで記述するのは効果あり
書籍では、「なぜこの要求を実現したいのか」という依頼者の思いを明らかにするため、要求は理由とセットで記述するよう紹介されています。

実際に理由を添えて記述することで、「そういえばこの要求はなぜ必要なのだろう?」と初心に立ち返りながら考えることができました。背景や理由を明文化することで、要求を実現するためのよりよい解に至ることもできるのではと思いました。

また、仕様の経緯を辿れるようにする意味でも、背景や理由をドキュメントに残しておく意義はあると思います。

tech-blog.rakus.co.jp

指示書(仕様書)を記述するときは、具体的な要求とその理由(背景)をセットで記述するのがベストです。
やっぱり、これが必要なのですね。

じつは、このように具体的な要求と理由をセットにしておくと、
・プリントが止まることが問題
・画質低下が起きることが問題
という本来の自分の要求が明確になったうえで、そのためにどう具体的に動くかが明確になります。

これは「作業者の納得感が増す」ということにも寄与しますが、目的が共有でき、最低限の具体的な指示も含まれるということになります。
目的が共有されていれば、その他の不具合も連絡してほしいということが想像できるようになります。

このような作業指示書は自身(作成者)より、経験が低い人へ向けて書かれることが多いですが、ソフトウェアの要求(または要件・制御)仕様書はかならずしもそうではなく、自分より経験が豊富な人(ソフトウェアエンジニア)へむけて作成されることもあります。

このとき、細かな指示をして、目的を共有しなければその通りの実装がされると思いますが、
目的を同時に共有していると、場合によっては受け手(ソフトウェアエンジニア)のほうがより良い方法を知っているかもしれません。
両者で詳細仕様の設計ということもできるのです。

まとめ

仕様書(指示書)を作成するときにいつも、理由の説明を含めるべきかどうか?を考えていたのですが、最近一つの解にたどり着きました。
上でも紹介したhttps://tech-blog.rakus.co.jp/entry/20200910/requirements-specificationでも書かれていることとも一致しますが、
指示書(仕様書)を記述するときは、具体的な要求とその理由(背景)をセットで記述するのがベストです。