(仕様書というよりは)資料を書くときにごく普通に意識していること。
■言葉を統一する
同じものを指すのなら、常に同じ言葉で書き表す。
■初出のものには説明を
重要なもの・ことについては、章を割いて説明する。
読み手の前提知識がどの程度で、どこまで説明を必要としているかを考える。
■説明の流れを意識する
「どう説明したらわかったもらえるだろうか?」を意識し、
絵や語句の登場順などの、各章の関連・構成を考える。
■図解
必要に応じて、文章や言葉を説明するための絵を示す
(文章を使って絵を説明する、とも言える)。
このとき、説明したい文章・言葉と絵が対応づけされていることが
読み手にわかるようにする。
おおざっぱにイメージで言えば
読み手を迷わせない、混乱させない、ムダに想像させない
ということだ。
こういう視点で見れるようになったのは
たぶんレビューでいろんな人の資料を見るようになったからなのだと思う。
そもそも私が仕様書の記述内容を考えるようになったのは、
「本当に欲しい資料がつくられていない」と感じることがあったからだ。
例えば標準化でフォーマットが決められていたり、過去の既存資料があった場合は、
「今までと同じようにつくっておこう」となりがち。
しかし、ある頃から「こんな資料ではシステムやプログラムの理解の助けにならないな」と思い始め
少しずつ自分なりに「必要と思う資料」を考えながら、起こしていくようになった。
これだと結局は個人が我流でやっているだけだ。
みんなはどうやって仕様書の書き方をおぼえてきたのだろう?
レビューで指摘することがちゃんと実地訓練になっているのか?
その人たちにとって「勉強」になっているのか?
現場では時間制限もあるので「魚を獲ってあげる」こともあるのだが、
どうやったら「獲り方をおぼえる」ことができるのか、考えてみないと、と思った。
上記はどちらかというと体裁のこと。本来は設計内容など、もっと技術的なことを気にしたい。
しかしこのようなこと(体裁)のためにとてつもなくコストをかけている。
資料作りやレビューがチームのテンションを下げないよう、
停滞感を和らげ、みんなで前に向かって進んでるんだよっていうムードづくりもまた大事だ。