Qiita Teams that are logged in
You are not logged in to any team

Log in to Qiita Team
Community
OrganizationEventAdvent CalendarQiitadon (β)
Service
Qiita JobsQiita ZineQiita Blog
1021
Help us understand the problem. What are the problem?

More than 5 years have passed since last update.

仕様書を書く上で必要かなと思うことをまとめてみた。
対象者は、まだ仕様書なんて書いたことないよとか、何書くかいつも悩む、という方。

ここでいう仕様書とは、開発前の設計書というよりは、運用フェーズに引き渡す前に用意しておいたほうがよいドキュメント、という位置づけ。

仕様書の目的

  • 仕様書を書く目的は、新しい人がチームに来た時に、スムーズに業務に取り組めること。
  • また、「人は時間が経つと必ず忘れる」ので、将来の自分のためでもある。

大事なこと

  1. 仕様書の目的を明確にする。
    • あれもこれも、と情報をたくさんのせても混乱する。
    • 「仕様書にもメンテナンスコストがかかる」ことに注意する。
  2. 仕様書は正しい日本語で書く。
    • 主語をきちんと入れることが大事(〜のつもりで書いた、というのは知らない人には伝わらない)。
  3. 情報は多すぎず、少なすぎず。
    • 条件について場合分けして整理したり、図を用いたりすると良い。
  4. 前提と制約についてはしっかりと書く
    • 明らかに無駄な処理に見えても、過去の経緯や制約からそうせざるを得なかった、ということもある。
    • 仕様書に書いていないと、誰かが知らずに修正して、バグになる可能性もある。  
  5. 用語を統一すること
    • 同じものを指しているのに、あるところではAと言っていて、別のところではBと言っているというのは、読み手に混乱を招く。
    • 用語については、最初のページなどに用語集として書いておくと、なおわかりやすくなる。

書くべきこと

仕様には大きく分けて以下のようなことを書いていくと良い。

  1. 画面仕様

    • 各画面内での操作の動き、画面同士の関係を示す。
    • 全体構成図・遷移図もあるとわかりやすい。
  2. 機能仕様

    • 個別の機能について、どういう目的で、何をするものなのかを示す。
    • 例えば、ユーザーの権限タイプによる挙動の違いなど、同じ機能を使う場合でも条件により処理が異なる時は、場合分けして整理しておくとわかりやすい。
    • 機能仕様は書いていくと細かくなりがちだが、「詳細ロジックはソースコードを読めば良い」ので、上述の前提や制約のようにソースを読んだだけではわかりづらいことを書いていくのが良い。
  3. データ構造

    • テーブルデータ構造を示す。データが何を指しているのか、どういう制約があるのかを示す。
    • エンティティ間の関係性(カーディナリティ、オプショナリティ)も書いたER図がよい。
  4. インフラ構成

    • どのバージョンのなんというミドルを使っているか、などくらいはまとめておく。
    • リクエスト制限、キャッシュ管理など、考慮が必要な情報があるなら、記載しておく。
  5. その他

    • 外部システム連携など、必要に応じて記載していく。

最後に

  • レビューをしていると「そこはこういうつもりでした」と言う人が多い。単純な記入漏れの場合もあるかもしれないが、「わかってくれるだろう」という甘えが出ているときもあるかもしれない。
  • 基本的に、他人に自分の考えは伝わらないという前提で書いていったほうがよい。思いやりの気持ちで!
Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
1021
Help us understand the problem. What are the problem?