仕様書は読まれない
仕様書は書いても読まれません。読まれないから更新されなくなり、現実との乖離がどんどん大きくなっていきます。乖離が大きくなると、誰も修正しようとは思わなくなり、ハイ、陳腐化した仕様書が出来上がります。
短い期間の2〜3人のプロジェクトであれば仕様書は不要かもしれません。だけど、それ以上の人数がプロジェクトに関わる場合はやっぱり仕様書が必要です。コミュニケーションパスが増えた場合は文章による伝達の方が（完全ではないにせよ）効率的ですし、そしてなにより、我々は忘れっぽい生き物なのですから。
仕様書が読まれない原因は？
Joelは「Joel on Software」の中で、仕様書が読まれないのは、それがあまりに退屈でつまらないからである。と言っています。もちろん読むための時間が不足しているとか その他の理由もあるかも知れませ。だけど、仕様書がちょっと楽しければ、時間を割いて読む気になってもらえるのではないでしょうか。
仕様書を書くためのヒント
「Joel on Software」では、上手くだまして仕様書が読まれるように仕向けるように、次のようなヒントを紹介しています。
- 可笑しくすること
- 人間が自然に理解できる流れで書く
- 出来る限りわかりやすく
- 何度も見直し、読み返す
- テンプレートは有害である
以下で、Joelの言うヒントを私の解釈で見てみます。
可笑しくすること
ある機能の動作を説明するのに、
ユーザはCtrl+Nをタイプして新しいEmployeeテーブルを作成し、従業員の名前を入力する。
と書くかわりに、
ピギー嬢は、彼女のまるまるした小さな指は太すぎて個々のキーが押せなかったので、アイライナー・スティックを使ってキーボードを突っつき、Ctrl+Nとタイプして新しいBoyfriendテーブルを作成し、レコード"Kermit"を1件だけ入力した。
と書いてみよう。としています。これはちょっと極端な例かもしれませんが、できるだけ具体的で風景がイメージとして想像できる文章で記載することは読み手を引きつける上で重要なことだと思います。
人間が自然に理解できる流れで書く
論理的には正しいけど、いきなり詳細が記載された文章は読みにくいものです。ロジカルライティングの基本通り、全体像を示し その後で詳細を埋めるような書き方が必要です。
出来る限りわかりやすく
テクニカルな言葉を乱用せず、簡単な言葉で、できるだけ短い文で書くこと。細かい記述は注記として書く。
何度も見直し、読み返す
何度も見直し、読み返す。超簡単ではない文章は書き直すこと。ライティングの基本通りですね。2〜3日置いておいてから読み返すのが良いと思います。
テンプレートは有害である
テンプレートに合わせて記述することで、無駄な記述が増え、重要な事柄がぼやけてしまいます。伝えたいことに合わせた構成とすることが重要です。
結局のところ
結局のところ、ライティングの基礎を身につけ、ひたすら練習することが重要そうですね。それと少しばかりのユーモアがあれば、理解しやすく記憶に残る仕様書になりそうです。
個人的には、なぜその機能が必要かというバックグラウンドを説明した記述が重用と思います。バックグラウンドの説明が無い場合は単にその機能を作るだけになりますが、なぜ の記述があれば、間違った認識によるあさっての実装がなくなり、さらには、より良い実装にするためのアイディアも生まれてくるのではないでしょうか？
