仕様書を書く上で必要かなと思うことをまとめてみた。
対象者は、まだ仕様書なんて書いたことないよとか、何書くかいつも悩む、という方。
ここでいう仕様書とは、開発前の設計書というよりは、運用フェーズに引き渡す前に用意しておいたほうがよいドキュメント、という位置づけ。
仕様書の目的
- 仕様書を書く目的は、新しい人がチームに来た時に、スムーズに業務に取り組めること。
- また、「人は時間が経つと必ず忘れる」ので、将来の自分のためでもある。
大事なこと
- 仕様書の目的を明確にする。
- あれもこれも、と情報をたくさんのせても混乱する。
- 「仕様書にもメンテナンスコストがかかる」ことに注意する。
- 仕様書は正しい日本語で書く。
- 主語をきちんと入れることが大事(〜のつもりで書いた、というのは知らない人には伝わらない)。
- 情報は多すぎず、少なすぎず。
- 条件について場合分けして整理したり、図を用いたりすると良い。
- 前提と制約についてはしっかりと書く
- 明らかに無駄な処理に見えても、過去の経緯や制約からそうせざるを得なかった、ということもある。
- 仕様書に書いていないと、誰かが知らずに修正して、バグになる可能性もある。
- 用語を統一すること
- 同じものを指しているのに、あるところではAと言っていて、別のところではBと言っているというのは、読み手に混乱を招く。
- 用語については、最初のページなどに用語集として書いておくと、なおわかりやすくなる。
書くべきこと
仕様には大きく分けて以下のようなことを書いていくと良い。
- 画面仕様
- 各画面内での操作の動き、画面同士の関係を示す。
- 全体構成図・遷移図もあるとわかりやすい。
- 機能仕様
- 個別の機能について、どういう目的で、何をするものなのかを示す。
- 例えば、ユーザーの権限タイプによる挙動の違いなど、同じ機能を使う場合でも条件により処理が異なる時は、場合分けして整理しておくとわかりやすい。
- 機能仕様は書いていくと細かくなりがちだが、「詳細ロジックはソースコードを読めば良い」ので、上述の前提や制約のようにソースを読んだだけではわかりづらいことを書いていくのが良い。
- データ構造
- テーブルデータ構造を示す。データが何を指しているのか、どういう制約があるのかを示す。
- エンティティ間の関係性(カーディナリティ、オプショナリティ)も書いたER図がよい。
- インフラ構成
- どのバージョンのなんというミドルを使っているか、などくらいはまとめておく。
- リクエスト制限、キャッシュ管理など、考慮が必要な情報があるなら、記載しておく。
- その他
- 外部システム連携など、必要に応じて記載していく。
最後に
- レビューをしていると「そこはこういうつもりでした」と言う人が多い。単純な記入漏れの場合もあるかもしれないが、「わかってくれるだろう」という甘えが出ているときもあるかもしれない。
- 基本的に、他人に自分の考えは伝わらないという前提で書いていったほうがよい。思いやりの気持ちで！