どうも、途中まで書いた記事を保存せずに閉じてしまった悲しみから立ち直れないオムそばです。
最近、現場で不具合報告の曖昧表現個所を指摘した際、「いやいや、画面見れば一発でわかりますよ」と返されたので、それでよいのか、について考えてみました。(その時に打ち返した内容も合わせて載せます)
■×:"画面見ればわかる" ○:"画面見なくてもわかる"
不具合報告は、「実際の動作を見ればわかる」ではなく、「実際の動作を見なくてもわかる」ように書く方がよいです。
理由は以下の通りです。
- 開発者が不具合報告を読んだとき、修正箇所の特定や、事象を理解するために、再現させなければいけないという手間が増える(それが、文言一文字間違っていた、などの細かく簡単な事象であっても)
- 開発者、テスト管理者が不具合報告を読んだときに、具体的な状態が把握できないため、重要度・優先度付ができない
- 一年後の自分が不具合報告を読んだときに、内容を忘れてしまい、具体的な状況の説明ができなくなる可能性がある
不具合報告に限らず、人が見るドキュメントを作る際は、それを見る"時間"、"人"、"状況"に左右されない書き方をされていることが、大切だと私は考えます。