仕様書の作成時に気をつけたいこと

はじめに

4月からエンジニアとして働き始めたひよっこです。現在所属にて開発の課題を進めている途中ですが仕様書の作成の際に勉強したことをメモ代わりにまとめておきます。自分で完結する開発したことしかなかったので"赤の他人が見てもわかるように"という視点が全く足りませんでした。次は今回勉強したことを活かして行きたいなと思います。

仕様書とは

どのような機能をもたせるのか、どこからどのように遷移させるのかを明記したものをいいます。発注者が存在する場合は受注側と一緒に協議しながら書いていくことが多く、発注側の要件を満たすことが求められます。

仕様書がなぜ重要なのか

仕様とは満たすべき要求事項のことを言います。満たすべきことを曖昧にした状態で開発を進めていくと発注側と受注側で認識に齟齬が生まれてしまいやすくなります。そういった誤解を解決するために作成するのが仕様書です。予め発注者側の要件に合わせて画面の仕様から機能の部分まで作り込むことによって工数の見積もりも立てやすくなりますし、急な変更などが起きづらくなるでしょう。

仕様書づくりのポイント

①全体像から詳細の説明でわかりやすい流れの設定

ものごとを説明する際にはわかりやすい順序というものがあります。１からものごとを説明する際には最初になんとなくで良いので全体像を説明しましょう。どんな流れで仕様書が書かれているのか、どんなwebアプリケーションなのかを最初に定義して、そこから画面の仕様や詳細な部分の説明をすることで読んでいる人は全体の中でどんな位置づけをしているのかをイメージすることができます。

②画面設計に画像や図を使う

視覚的に理解するものを文字で伝えようとすると誤解が生まれがちです。なので画面を説明する際には積極的に図や画像を活用することで視覚的に理解できるようにしてみましょう。足りない部分を文字で補うような形で進めていけば、見る人も確認しやすくなります。

③曖昧な部分は自分で判断しない。

仕様書の作成後に成約や機能については元も子もありません。要件について不明瞭なものについては積極的に確認、仕様書の時点で発注側と完成のイメージが共有できるようにしましょう。

④言葉は正確に

作成中に私もやってしまいました｡
ex)この、その
を多用すると結局どの言葉を指しているのかが分かりづらいです。なるべく主語ははっきりと統一して使用するようにしましょう。

⑤データベースの設計

例
データベース名：database_name

テーブル名：table_name

上記の4項目でまとめるようにします。NOT_NULLやDEFAULTについてはOPTIONで設定するようにします。カラム名やデータ型についてはデータベース設計については別の話になってくるのでOPTIONやデータ型については別途調べてみてください。

参考文献

エンジニア歴20数年の私が、設計書を書く際に心がけていること