読者です 読者をやめる 読者になる 読者になる

Some Days You Get the Bear

IT系エンジニアの、日々の気づきや考えたこと。

仕様書の書き方はどうやっておぼえるのか

(仕様書というよりは)資料を書くときにごく普通に意識していること。

■言葉を統一する
 同じものを指すのなら、常に同じ言葉で書き表す。

■初出のものには説明を
 重要なもの・ことについては、章を割いて説明する。
 読み手の前提知識がどの程度で、どこまで説明を必要としているかを考える。

■説明の流れを意識する
 「どう説明したらわかったもらえるだろうか?」を意識し、
 絵や語句の登場順などの、各章の関連・構成を考える。

■図解
 必要に応じて、文章や言葉を説明するための絵を示す
 (文章を使って絵を説明する、とも言える)。
 このとき、説明したい文章・言葉と絵が対応づけされていることが
 読み手にわかるようにする。

おおざっぱにイメージで言えば

 読み手を迷わせない、混乱させない、ムダに想像させない

ということだ。

こういう視点で見れるようになったのは
たぶんレビューでいろんな人の資料を見るようになったからなのだと思う。

そもそも私が仕様書の記述内容を考えるようになったのは、
「本当に欲しい資料がつくられていない」と感じることがあったからだ。
例えば標準化でフォーマットが決められていたり、過去の既存資料があった場合は、
「今までと同じようにつくっておこう」となりがち。
しかし、ある頃から「こんな資料ではシステムやプログラムの理解の助けにならないな」と思い始め
少しずつ自分なりに「必要と思う資料」を考えながら、起こしていくようになった。

これだと結局は個人が我流でやっているだけだ。
みんなはどうやって仕様書の書き方をおぼえてきたのだろう?

レビューで指摘することがちゃんと実地訓練になっているのか?
その人たちにとって「勉強」になっているのか?
現場では時間制限もあるので「魚を獲ってあげる」こともあるのだが、
どうやったら「獲り方をおぼえる」ことができるのか、考えてみないと、と思った。

上記はどちらかというと体裁のこと。本来は設計内容など、もっと技術的なことを気にしたい。
しかしこのようなこと(体裁)のためにとてつもなくコストをかけている。
資料作りやレビューがチームのテンションを下げないよう、
停滞感を和らげ、みんなで前に向かって進んでるんだよっていうムードづくりもまた大事だ。

広告を非表示にする