新人育成OJTネタです。
仕様書を作成してもらっていると出てくるのが、記載の過不足。
「過」の方は書かれていないわけではないので、説明が余計とか二重になっているとかでレビュー等でこうしようと言えるわけですが、「不足」の方だと読んでもわからない状態になります。
説明が不足していると、当然 読んでいる側も理解できませんので、レビュー時には質問になります。その時に説明はしてもらえるわけですが、それだったら「なぜ書かないのか?」ということになります。
おそらく仕様書を書いている側からすれば、自分では頭の中でイメージできていることもあり、ドキュメントへの記載が多少不十分でも、自分の頭の中で補完できてしまっているので、気づかなかったりするのかもしれませんね。
自分が理解していることでも、それをアウトプットした際には、情報が欠けてしまうことは普通にあると思います。
そのためにも、第3者とのレビューは絶対にやった方がいいです。
何も知らない人が読んでも理解できれば、それでそのドキュメントとしては説明したいことが表現できていることになりますので。
私も文章を書くのは決して得意ではないので、伝えにくい内容を説明するときは、絵(図)を使います。
描くのは多少面倒でも、やはりイメージ図があると、「こういう事を言っているのかな?」と相手も理解しやすくなりますし、ミスリードを減らすことにも繋がります。
その情報の欠落をいかに少なくするか、正確に伝えるかという努力は大切ですね。