外部仕様書（製品仕様書、基本仕様書）の書き方について説明します。
製品のミッションを中心に据えるという考え方で、基本仕様書の書き方を説明します。
「仕様を仕様書に書かなければならない」というトートロジー（いわゆる小泉論法）を理解することができれば、仕様書への見方が変わります。
仕様書を書くという創造的作業
ITエンジニアの世界で、仕様書を書くと言う作業は最も創造力を必要とするものです。経験がものを言う職人的な仕事でもあります。同時に楽しい仕事です。つまり、仕様書を書くという作業は、創造的、職人的であり、楽しいものです。
創造的で今まで誰もやったことがない作業を考え抜き、しっかりとした仕様書を作るというのは、時にはそのプレッシャーに押しつぶされそうになったり、「お前は敵だ！」という風にレビューしてくる人の悪意にさらされることがありますが、基本的には創造的で楽しいものです。
この創造的で職人的な仕様書を書くという作業を、もっと創造的、職人的な作業として突き詰めていくと、もっといい仕様書が書けますよ、というのがこの記事の主張です。
目次例には従いつつも本質を見失わない
どの会社にも、仕様書の目次例みたいなものがあると思います。なくても、過去の仕様書を参考にして仕様書を書くのが普通です。
目次例は、検討しそこなうこと、書きそこなう事を防止してくれるので、とても有用です。しかし、目次例ばかりに目を向けていると、本質的なことを語らない仕様書になってしまうことがあります。
「仕様書に仕様が書いていない」という屈辱的な指摘を受けることになるかもしれません。
下記の様に、製品の中心となる仕様（ミッション）を定めて、目次例にある項目を論理的、有機的に繋げていくと、とても見晴らしの良い仕様書になると思います。
製品の中心となる仕様（ミッション）を考える
製品の中心となる仕様（ミッション）とは、「製品XXXは、XXXXである」というような文章のことを言います。
高機能になってくると、一文で収まらなくなったりするので、箇条書きにしたり表にしたりして表現します。仕様書を書き始めたときにこの文章を考え、書き進めるうちに何度も書き直します。
製品の中心となる仕様（ミッション）を言葉にするという作業は、仕様書がよりよいものになるための創造的な作業ですので、ぜひやってください。
以下にも詳しく書きました。
>>> ITエンジニアが仕様書に最も書かなければならないたった1つのこと
システム構成
製品の中心となる仕様（ミッション）を書いた後は何の仕様を書くべきか？
どう書こうと自由ですし、最終的に全部書いてあればよいと思います。目次例がこの順番に書け、というかもしれませんし、本記事での書く順番は一例です。
本記事では、次にシステム構成を書くことにしてみます。
私は、システム構成として、ハードウェア構成、ソフトウェア構成を一気に書いてしまうことが多いです。
製品の中心となる仕様（ミッション）を満たすためのシステムは複数あると思いますので、逆にこのシステム仕様だったらミッションを実現できる、という形で書きます。
どういうシステム構成にするかは、設計者や周りの技術者が経験あるものになります。というかそうしておかないと、トラブルが起きたときに対応できません。
ハードウェア構成は、クラウドかオンプレか、規模によって複数サーバにするとか、冗長構成などを決めます。
ソフトウェア構成は、自分たちで作成するソフトウェアとミドルウェアやOSSなどをどう配置するかという外部的なもの、自分たちが作成するソフトウェアの内部構造というものがあります。
どちらにしても、ミッションから導かれるものではなく、これであればミッションを達成できるという主張をします。
内部仕様的なものにも見えるので、人によっては、システム構成を基本仕様書の最後に書くかもしれません。
ミッションから導かれる仕様たち
ミッションから導かれる仕様を説明します。必ずしもミッションから直接導かなくてもいいですが、ミッションを根拠にして、仕様を記述すると、とても説得力が高くなります。
以下のようなものは、ミッションの一部にするか、ミッションを根拠にして、XXXをするためにXXXにする、というような書き方がいいです。
- 正常系の機能
- 外向けのインタフェース仕様
- セキュリティの仕様
- 異常、例外の仕様
- 性能仕様
- ユーザインタフェース
正常系の機能
- ミッションを実現するための機能
- ミッションを補完するための機能
をミッションがこうだから、こういう機能があるといい、という風に作っていきます。
初めてレビューするときに、「その機能は何のためにあるのか？」という指摘が出ないようにしましょう。
すべての機能をミッションに含めてしまう人もいれば、ミッションは最低限にして他機能は別章という人もいます。書きやすい方で書きましょう。
外向けのインタフェース仕様
外向けインタフェースにはRFCやIEEEで定められていて選択の余地がないときもあれば、自分で何を選んでもよいというときもあります。
そのときの流行、チームの経験などを考慮してプロトコルを決定します。
ミッションの機能を外に向ける、と考えると自ずと必要なインタフェースは決まります。
「何に使うか分からないけど大量にAPIを公開する」みたいな方針はやめましょう。
セキュリティの仕様
通信は暗号化必要か、ファイル保存時暗号化するのか、は「何を守らなければならないか？」に依存します。
セキュリティを強くすると手間は増えますので、何をどのくらいの強さで守るのかをちゃんと考えておきましょう。
異常、例外の仕様
以下のように明らかな異常事態は分かりやすいです。起きたときに何をするかを決めておきます。syslogとかイベントログとかで「ユーザ通知」は最低限です。冗長構成になっている場合などはフェールオーバするとかですね。
- 外部機器が異常応答する
- ネットワーク障害
- ディスク障害
- 矛盾するデータを見つけた
重要なのは、製品機能を実現できなかったときの「異常」があるかどうかです。
たとえば、「充電するサービス」は「充電できない」という異常事態があります。「ものを運ぶサービス」は「ものを運べない」という異常事態があります。
製品のミッションに反する事項を検討し、異常事態をどう定義するかをしっかりと悩みましょう。
性能仕様
性能仕様は、ミッションを達成する上で必要な性能を決定します。
経験上、基本仕様書に書いてないことが多く忘れがちです。
機能を実現できれば「常識の範囲の性能」であればいいよ、ということだと思いますが、
「常識の範囲の性能」を一応決めておきます。
ユーザインタフェース
フレームワークにどれを使うかなどを考える前に「何をユーザに見せて何をユーザに設定してもらわなければならないか」をミッションから考えていきます。
「機器の稼働状況」「アクセスの統計情報」などをビジュアルに見せることが喜ばれるかもしれません。設定は、設定ファイルをテキストでいじってほしいというよりも画面で設定できる方がよいです。「ログの回収」「プログラムのバージョンアップ」など保守的な画面もできれば欲しいです。
何が欲しいかを考えると無限に出てきますので、バージョンアップのたびに整えていくという方針でもよいかと思いますが、ミッションから直接出てくるようなものは最初から実装すべきです。
「今、何を最も実装すべきか」をミッションから見極めていきましょう。
まとめ
外部仕様書（製品仕様書、基本仕様書）の書き方を「ミッション」を中心に据えて説明しました。
ITエンジニアとしての能力を高めて収入を上げていきましょう。
コメント