仕様書の書き方を考える

6,7,8月とそこそこ忙しかったのも、もう昔の話。

大分まったりできて幸せです。こんばんは、お久しぶりです。椛澤です。

色々落ち着いてきたので(フラグではない...はず)、ここ最近で思ったことをまとめておく。

 

仕様書書いといて

ちょうど一年前に配属二ヶ月くらいで言われて、いや書き方わかんねーけどwとか思っていたのが懐かしい。

気づけば誰も書いてないので、暇を見つけては仕様書に追加要件を加えたり、キャプチャを取り直している自分が居る。

一年前の自分に言いたいのは、とりあえず既存の物をパクって、わかんなかったら聞いて、気になったところがあれば追記して行く。というスタイルを確率する事だと思う。

何事も経験で、ある程度なれてしまえばいろんな人から意見を聞いてより良いドキュメントを作って行くのがそんなに大変じゃなくなる。

少なくとも1年前の僕は「仕様書書いといて」と言われたら、今にも吐きそうな顔でエクセルを開いていたと思う。

 

具体的に気をつける点を自分の経験からいくつか。

多分三年後に見たらまた変わっているのだろうと。

1.細部にはこだわりすぎない

そもそもの仕様書の目的として、機能の目的/概要/要件がまとまっていればそれで事足りる。それをまとめるのがとても大変なのですが。

細部にこだわらないといっても、機能を省略して書くのではなくて、デザインや細かい文言、バリデーションは別資料によせたりして、とにかくシンプルに保つ。

あくまで、要件(なにがしたくて、どうするのか)をシンプルに、分かりやすく書く

2.不具合が生まれそうなところは備考に書いておく。

仕様書だけではシステムにならないし、結局誰かがそれを見て実装する。(たいていの場合は一週間後の自分)

バリデーションに関しては別資料にまとめておく事が多い。入力必須かどうか、数字の範囲はどこまでか、他機能への影響はどこまであるのか。

余白的なところがあれば、テスト観点を書いておくのも効果的だと思う。

この機能Aは他の機能Bの表示に影響があるので、結合テスト時に見ておくこと。とか

3.デザインに詳しくなくても書ける事はある

当時はCSS全然わかんないんで無理です。。。と言って逃げていたけど、それでも文字に起こせたりする事は意外とたくさんある。

・デフォルトはどう表示される?

・何も値が無い時はどう表示する?

・長い文字列が入力されたら、...を使って省略する?それとも折り返す?

この三点くらいは少なくても想定出来るし、そんなに難しくはないはずだ。

こういう所をすっぽかしていると、後々になってどこどこと表示を揃えようってなって工数が少しずつかさんでいくのを何度も経験した。

 

4.マトリクスが役に立つ

画面設計書付きの仕様書では中々出来ないが、ステータスの管理を行う時はマトリクスはほぼほぼ間違いなく必須

「申請前ステータス」なら、ボタンはすべて活性

「作成済み」ステータスなら○○の変更はできないし、ボタンも非活性

なんて文字列を並べられるよりもずっと実装の手助けになる。

さらに大きいのは試験観点としても重要な資料となる。特に実装者以外の人にテストを行ってもらう場合は、こういった資料が認識に齟齬が生まれる文字ベースよりもずっと間違いが無い

 

 

振り返り

今のプロジェクトがテストフェーズに入ってきて、仕様書をもっとしっかりまとめておけば良かったと思う事が多々ある。

というのも、仕様書にまとまってたつもりが実は自分の頭の中で完結していて、他人にテストを任せた時に「いや正常な動作なんだよ」と突っ込まれるケースがあまりにも多かった。

(俺の仕事は実装で、担当プロデューサーが仕様書まとめるんだけどね、本当は)

 

 

最近IE対応を人生で初めてやっていろいろTipsたまってきたので、近々まとめて記事にします