＃ソース元は「誰にでも伝わるSEのための文章術-第6回 読みやすい文章の極意は「修飾語」にあり」です。
「あぁ、そうやなぁ」と思うようなことが、分かりやすい例とともに記述されています。
今まで書いたドキュメントを見直しても、NGケースに当てはまるものが1つはあるかと思います(苦笑)。
で、この記事を読んで思ったことをつらつらと書いてみます。
システム開発などの設計書を書き上げた(書いている途中含む)後、レビューまでに自分でどういう点に気をつけているでしょうか？
できれば、上記記事にあるレベルはクリアしたいものです。結果的に完全にクリアできていなくても、その視点で見ておくことでも意義があると思います。
レビューの大きな目的の1つは、「記述内容に齟齬がないか？」を確認することです。
そのレビューに、上記記事にあるNGケースが多くあると、目的に行き着く前にレビューアとして「ここの解釈はAですか？Bですか？？」と確認をしたりして、時間が余計にかかってしまいます。時間だけでなく、集中力も使ってしまいます。
以下は、そういうドキュメントを書くために、気をつけていることです。
1：「都度」確認する
一気に書き上げた場合…特に勢いに任せた場合、NGケースにひっかかるような内容になることが多い気がします。
一段落書いたら、先に進む前に、それまでの段落と今回書いた段落の整合性、単語の齟齬がないか確認します。
最後まで書き上げてから、チェックして統一性を取るのは、量もあるでしょうし大変です。
＃テストファーストやTDDと同じ感覚で、ちょくちょく確認しましょうというものです。
2：視点を変える
文章を書くお約束で「ラブレターは一晩寝かせてから(読み直して)送る」というのがあります。
書き上げた直後は脳内補完がかかってしまい、その文章の確認が甘めになってしまいます。
なので、一息置いて…これが「一晩寝かせて」ですが…レビューアや受け取り側の視点で読み直してみます。
＃当たり前のことですが、これらを含めた上で「ドキュメントを書き上げる」工数を見積もるのが前提です。
誤字・脱字はチェックできているなら、もう一歩進んで、この記事にあるポイントもチェックして、本来のレビューの目的を達成できるように心がけたいものです。
コメント