仕様書と設計書の違い
TL;DR
お客と合意できるのであればなんでもよいけどね（投げやり）。
意外と奥が深かった？仕様書と設計書の違い
某所で色々初心者向けの解説記事を書いてます。「小学生にもわかるように」と言われてますが、さすがに小学生は理解できないかも。それはさておき、決められたテーマをもとに記事を書いていくのですが、そのお題一覧の中に「仕様書と設計書の違い」というものがありました。
前職時代、腐るほど書いてきた仕様書や設計書。あまりに当然すぎてあまり厳密に考えたことはないな、と気づきました。
前職の会社では各種仕様書や設計書のテンプレートがあり、過去のシステムのドキュメントもあるので、たいてい前例踏襲となってしまいます。あまりよくないことではありますが、これもまたあるあるかと思います。
そんなわけで、これが仕様書でこれが設計書だ、という定義はあまり気にしたことはなかったので、この機会に調べてみました。（このお題で某所の記事を書くかは別として）
仕様書は結果、設計書はその過程
困った時のGoogle頼り。早速検索してみるといくつか解説記事が出てきました。
例えばこんな説明がありました。
「仕様書」は完成イメージを明確にした資料であるのに対し、「設計書」は完成するまでの制作工程を明確にした資料。
Monstarlab Blog：仕様書とは？開発事例をもとに成功する仕様書の書き方を解説
つまり「こんなWebサービスやアプリを作りたい」という要求に対し、仕様書は着地・結果を示すもので設計書は制作過程を示すものということです。
別の記事ではこんな説明でした。
・仕様書には「結果」が書かれています。設計書には「過程」が書かれています。
「分かりそう」で「分からない」でも「分かった」気になれるIT用語辞典：「仕様書」と「設計書」の違い
・仕様書は、それを見ても作れません。設計書は、それを見れば作れます。
・仕様書は、技術的なことを知らなくても作れます。設計書は、技術的なことを知らないと作れません。
・受託開発の場合は、お客さまと一緒になって作り上げるのが仕様書です。作る人たちだけでえっちらおっちら作り上げるのが設計書です。
どちらも仕様書は結果を示すもので、設計書は過程を示すもの、という部分は一致しています。
個人的には結果というと終わったもののように感じるので「目標」と言い換えた方がいいようには感じますが、おおむね同意できます。要はこういうものを作ります、というものです。
「結果」という言葉に抵抗を感じるのは、仕様は場合によっては変更されることもあるため。結果というともう確定という感じがありますが目標なら見直すこともありますよね。まあ、イメージ的な問題であまり本質的なことではないので、これ以上は特に掘り下げません。
そもそも「仕様書」を書くか？
仕様書と設計書について考えてきましたが、ふと気になりました。そもそも「〇〇仕様書」ってドキュメントをそんなに書いたっけ？ということ。
ソフトウェア開発で書くドキュメントについての記事は以下のものなどがありましたが、ここに出てくるのも「〇〇テスト仕様書」くらいです。
https://mama-sun.com/jp/bpotimes/257/確かに、大昔は設計書がかなり細かく分かれていて、例えば画面周りだけでも画面一覧、画面仕様書に分かれていたり。他にもファイル仕様書、帳票仕様書や入出力仕様書と個別に分けていたように思います。ただ、その後それらを一つの基本設計書の中の章立てに組み込んでしまうことが多くなったように思います。これは会社や職場、プロジェクトの考え方も大きいので、うちは違う、今でも分けているというところもあるかとは思います。
まとめるか分けるか、それぞれ表裏一体のメリット・デメリットがあります。
- 個別に分けるとファイルが増えて管理しにくい
- 一方、まとめると版管理がわかりにくい
- 変更履歴も長くなるし、やたらとバージョンが上がりかねない
例えば、前職の会社はテスト仕様書とテスト報告書が一体で、「テスト仕様書／報告書」でした。これも管理上、メリット・デメリットがあるとは思います。
個人的には紙ありきの時代は比較的細かく分かれていて、ファイルありきになってからはまとまっていったような記憶もあるように思いますが、定かではありません。
無理やり理由づけすると、紙時代はパッと目的のところに飛ぶにはそもそも物理的に細かくドキュメントが分かれていた方が便利で、ファイルになって目次からパッと飛べるようになると1つのファイルにまとまっていた方が便利になった、なんてことも考えましたが、どんなものでしょうね？
フェーズ毎にフォルダを分けるにしても、〇〇設計書、〇〇仕様書がずらっと並んでいる中から目的のドキュメントを探すより、パッと〇〇設計書ファイルを開き、その目次から目的の項目（画面一覧、画面仕様、ファイル仕様、等など）にジャンプするのが早そうです。結構、いい線いってるのではないかと思うのですが…。あとは、当時のコンピュータではなんでもまとめた巨大設計書を作るとコンピュータのパフォーマンス的に追っ付かないという切ない事情もあったかと思います。
違うものだったが、今は設計書にまとまっている？
というわけで、「仕様」と「設計」については最初に引用したような結果や目標と、作るための過程を示すという違いはあると思います。ただ、「仕様書」と「設計書」となると、もはや「〇〇仕様書」という単体の仕様書を書くことが極めて少なくなっているように感じてきました。
もちろん、これは自分の周りの事情だけなので、世の中一般でどうなっているかは分かりません。
「仕様書、書いてますか？」
要件定義書と仕様書
最初、このネタを考え始めた時、「仕様書」として思いついたのは「要件定義書」でした。名前にこそ「仕様」が含まれませんが、これはお客さんと開発側でどういうシステムを作るか、つまり「仕様」を定めた重要なドキュメントとなります。仕様定義書と置き換えても過言ではないかと思います。思いますが、混乱するだけなので「要件定義書」と呼びますけど。
そういう意味では2つ目に引用した記事の最後のポッチ、「客と作るのが仕様書、開発側が作るのは設計書」の「仕様書」は実は要件定義書のことじゃないかと思えてきます。
というのも、テスト仕様書（特に結合や単体）は客と作ることは普通はないです。画面仕様や帳票仕様は客が関わることはあるでしょうが、入出力仕様やその中でもシステム間の入出力仕様なんてあたりは基本的には開発側マターです。仕様といっても、外部仕様と内部仕様があり、外部仕様は客マターのことが多いですが、内部仕様は開発マターだと思います。ざっくり言えば外部仕様＝要件という認識でもよいかと個人的には思います。
つまり、仕様書でも必ずしも客と作ったり、客が関わるというものではないわけです。一方、要件定義書は確実に客が関わります。
それもあって自分も最初は仕様書と言われて要件定義書を思い浮かべてしまいました。
外部仕様、内部仕様と関連して、外部設計、内部設計という言葉もあります。基本設計、詳細設計のことと思っておおむねあたりです。
外部使用に関わる設計が外部設計、内部使用に係る設計が内部設計、というわけですね。
基本・詳細設計の代わりに外部・内部設計という言葉を使おうという主張がありますが、自分の周囲ではあまり流行ってないようでした。
皆さんの周りではいかがでしたか？
私家版：仕様書と設計書の違い
以上つらつらと書いてきましたが、個人的に仕様書と設計書をまとめるとしたらこんな感じでしょうか。あくまで個人の感想レベルですけど。
- ソフトウェア開発では仕様が重要
- 仕様とはそのソフトウェアの決まりのこと
- 例えばどんな画面があり、その画面にはどんな部品があるか。それを操作するとどうなるか等など
- 仕様にはユーザに直接関わるもの「外部仕様≒要件」と、関わらないもの「内部仕様」がある
- 仕様を元にどうやって実現するかを考えるのが「設計」、実際に書くのが「コーディング」
- 仕様を書くのが「仕様書」、設計を書くのが「設計書」
- ただし、現在は「仕様書」を書く機会が少ない気がする（各種テスト仕様書くらい？）
- では仕様はどこにあるかといえば、設計書の一項目になってしまっていることが多い
- だからこそ、「仕様書？設計書？」という混乱が起きてしまう？
- その中でも外部仕様を顧客と合意する「要件定義書」は名前に「仕様」こそつかないが代表的な仕様書
こんなことを書いてきましたが、極めてたくさんの画面とかファイルがあるような巨大システムでは、おそらくドキュメントをまとめてしまわずに細かく分けているのではないかと想像します。自分が関わったような規模であれば画面はせいぜい十数〜二、三十程度ですので、一つにまとめてしまっても問題はあまりありません。
しかし、それが3桁オーダーとかになれば、一つの巨大ファイルにするのも無理があるし、画面関係は画面関係、帳票関係は帳票関係とある程度分けた方がわかりやすいかと思います。
蛇足：流石にこの内容を初心者向けに書いてもわけわからんよなぁ。