役立つ仕様書を書く
2022年05月11日
(この記事で仕様書と書いている部分はすべてソフトウェシステムの機能について説明した機能仕様書を指しています。)
私はシステム開発において機能仕様書を重要視しています。
仕様書をうまく使うことで、コストを減らしたり、リスクを減らしたりとユーザーにとっても開発会社にとっても良い効果があると感じているからです。
この記事では仕様書のメリットや、どういう点に気をつけて仕様書を書いているのか、私の知見を書いてみます。
Contents
仕様書を書くのは嫌いじゃない
個人的な嗜好ですが、仕様書を書くのは嫌いではありません。
一般にエンジニアはドキュメントを書くのを嫌うとのことなので、こう考えるのは珍しいのかもしれません。
同僚とドキュメントについて話したときも、その場の全員が仕様書を書くのが好きではないとの返事でした。
システム開発をする上で不要な作業なので書きたくないそうです。
ただ私の認識は逆で、仕様書を書くことはコストパフォーマンスの高い行動だと考えてます。
開発全体を通してみたとき、仕様書があることでコミュニケーションコストを減らし、実装時に何を作ればよいのか明確になり、手戻りのリスクも抑えられる、など多くのメリットが見込めるからです。
当然意味のないドキュメントを作っても効果は期待できませんが、目的を持って仕様書を作れば多くのメリットが得られます。
以下、効果的に仕様書を作成、利用するために心がけていることを書いていきます。
仕様書を書く理由
仕様書を書くことによって以下のメリットが期待できます。
- コスパが良い
- コミュニケーションコストを減らせる
- 一度仕様書を書けば、仕様書を説明に使える。
- 工数を減らせる
- 仕様書はすぐに修正できるが、コードを修正するのは時間がかかる。コードで試行錯誤するより仕様書で検証/手直しするほうがコスパが良い。
- コミュニケーションコストを減らせる
- あとからでもスタッフが参加しやすい
- システムを理解するために仕様書を使える
- リスクを減らす
- 問題を言語化することで間違った問題を解決しようとするリスクを減らす
- 解決法を言語化、レビューすることで良くない解決法を採用するリスクを減らす
仕様書はどういう問いに答えるものか?
あらゆるドキュメントは、なんらかの問いに対するアンサーであるべきです。
読む労力に対する対価があるからこそ、人はドキュメントを読もうとするからです。
仕様書は以下の問いへのアンサーです。
* システムが解決する問題は何か
* システムが提供する機能は何か
* 各機能と問題の関係
仕様書を何に使うか
仕様書を利用するのは以下のような場面です。
* ユーザーが自分の問題を解決できるか判断するため
* エンジニアが開発対象機能を理解するため
* テスターがテスト計画を立てるため
* 受け入れテスト時に必要な機能が提供されているか判断するため
ユーザーは開発するシステムが問題解決に役立つか、システムが完成する前に検証することで、手戻りのリスクを減らせます。エンジニアやテスターにとっても作業の計画を立てられるようになります。
効果を高めるために、私はユーザー、エンジニア、テスターと仕様書の読み合わせの機会を設けるようにしています。これによって検証効果やメンバーのシステムへの理解度が大幅に上がりますので、読み合わせにかけた時間以上の効果が見込めます。
仕様書はウォーターフォール開発のためだけではない
アジャイルプロジェクトだから仕様書は作らないんだ、というような話を何度か聞いたことがありますが、私はそうは考えていません。
アジャイルソフトウェア開発宣言には「包括的なドキュメントよりも動くソフトウェアに価値を置く」と書かれていて、これが一人歩きしてそのような誤解につながったのかなと思います。
しかし、アジャイルソフトウェア開発宣言はドキュメントを作らないほうが良いと言ってるのではありません。
動くソフトウェアの方が、より重要と言ってるのです。
また、同宣言には価値を置くこととして「個人と対話」「顧客との協調」「変化への対応」を挙げています。
仕様書によってコミュニケーションコストを減らせ、システムについての理解を深めることができるなら、「個人と対話」「顧客との協調」「変化への対応」にもプラスになるので、アジャイル開発にも使えるツールだと言えるでしょう。
仕様書に含めるコンテンツ
仕様書で伝えたいことは、「何を開発するのか」です。
それを伝えるために以下のコンテンツを含めるようにしています。
画面遷移図
ページ間の関係を図示します。
システム全体像を把握するのに使います。
画面の説明
画面の説明はこれまで試行錯誤した結果、今は下記のフォーマットで書いてます。
画面名: 画面の番号とページ名を表示します。
左列 画面ワイヤーフレーム: 説明する要素に要素番号をつけます。
右列 説明欄:
要素番号ごとに説明を記述します。
また、要素以外の挙動、制約などの説明もここに記述します。
画面と要素にIDをつけるとピンポイントに説明、議論ができて便利です。
その他のコンテンツ
その他必要に応じてユーザーへの説明、認識があってるか確認したいことなども仕様書に含めるようにしています。
例えば以下のような内容を書きます。
- システム開発の目的
- システムが解決する問題の説明
- システムが解決する問題の範囲
- 用語集。用語集で定義された言葉を仕様書で使うときは、そのままの語句を使い、表記ゆれがないように気をつけます。
- システムが利用されるケース
- 想定するユーザー
- 提供する機能一覧
- 業務フロー
- データの状態遷移
掲載するコンテンツは目的に応じて変える
上に挙げたコンテンツは、いつも同じものを書くわけではありません。
「コミュニケーションコストを下げるためには何を伝えるべきか」「誰に何を伝えれば開発の手戻りを少なくできるか」を考え、それに必要なコンテンツのみ含めます。
まとめ
仕様書には以下のメリットがあります。
- 仕様書はコスパが良い
- コミュニケーションコストを減らし、手直しのコストも少ないです。
- メンバーが参加しやすくなる
- 仕様書はリスクを減らせる
- 正しい問題を正しく解決しようとしているかの検証に使えます。
効果的な仕様書を作るポイントは、コスパに気を配ることだと思います。どういう情報があるとどのように無駄なコミュニケーションを減らせるのか想像することが重要です。
うまく使えれば、かけたコスト以上に多くのメリットが得られる優れたツールです。
以上、仕様書についての知見の共有でした。仕様書作成/運用の参考になれば幸いです。
関連記事を見る
この記事を書いた人
2022年05月11日
記事のカテゴリ：Webシステム開発
STAFF募集
メディアマックスジャパンではWebエンジニア・プログラマー、フロントエンドエンジニア、デザイナー、マーケターを募集しています。詳しくは求人採用情報をご覧ください。お問い合わせやご応募はX（旧Twitter）とFacebookでも随時受付中です。
