SEの仕事をするにあたり、ぱっと見でわかるドキュメントを作成できることは重要です。わかりやすいドキュメントを作成することにより、情報を『正確』に『早く』伝えあうことができます。
今回は、ドキュメント作成における失敗と教訓をお伝えしたいと思います。
■失敗談
私はリーダから、「条件ごとの、画面の遷移先がわかる資料を纏めて欲しい」との依頼を受けました。そこで、以下のような表を作成いたしました。
パターンが網羅できており、表だからわかりやすいだろうというという意識で提出しました。
ところが、リーダーから、「イメージと違う」というダメ出しを受けることになりました。
なにが問題だったのでしょうか？
■問題点
依頼者の求めているイメージとずれていたことが問題でした。
このドキュメントは「条件ごとの画面遷移先の方式について顧客に説明し、ご指摘・ご承認を頂く。」ことを目的としています。
そのために必要な情報として、以下の２点が必要となります。
- ①遷移のパターンが漏れなく記載されていること
- ②遷移のイメージが一目で把握できること
当資料では①を満たしていましたが、②の観点において、ぱっとみわかるものではなかったのです。
画面は別紙参照と記載していたので、そちらを見ればわかりますが、一覧性には乏しいです。
■なぜそうしてしまったか
依頼事項の「条件ごとの、画面の遷移先がわかる資料を纏めて欲しい」を額面通りに受け取り、それを満たす資料を作成しようと考えていました。逆にいえば、それを満たしていればよいと考えていたところがあります。
ドキュメントは、誰かに情報伝達する為の手段といえるので「相手が何を欲しているのかを考え、確認する」ということを常に行っていくべきでした。
■対応後
依頼主が欲している、遷移のイメージが目で浮かぶような資料に変更しました。
画面遷移のイメージが、先ほどよりわかりやすく記載されていると思います。
■結論
ドキュメントというのは、同じような内容であっても、伝える目的によって表現方法が変わるものだと思います。
例えば、テスト仕様書を作成するのであれば、網羅性が一目で認識できる前者（表形式）の表現の方が優れているのではないでしょうか。
受け手のことを考え最適な表現方法を模索することが重要だと考えます。
