A good report is knowledge shared clearly, correctly, comprehensively, consistently and concisely. As testers, we spend a lot of our time dealing with reports that lack some or all of those and it should be important to us professionally, and also in our selfish interests, to maximise the signal/noise ratio of our own writing.

But it’s easy to forget to think about it and even when reviewing reports before submission it’s easy to not notice issues, given the full context of the situation is usually uppermost in the mind at the time. Here’s a few of the common traps I’ve fallen (and fall) into:

  • “In a meeting it was decided that we should …” Meeting with who?  Were there alternatives, are there minutes to link to?
  • “It all goes wrong”, “It just doesn’t work” In what way, what do you see, why is that unhelpful?
  • “It is not possible to …” Are you sure? Just what did you do to try to make it happen?
  • “We observe A, we might want B … The product manager says this is expected.”  Which “this”?
  • “The bug about that thing”. Why not find the bug number and reference it?
  • “The thingy object” as in  “I built a difficult object to input”. What do you mean by “difficult”? Can you just attach the item you built rather than describing it?
  • “I see an error” What does the error say?
  • Writing swathes of text to describe an effect when an annotated screenshot would do it better.
  • Giving paragraphs of background before the meat of the the report. Push it to the bottom, or even a separate comment.
  • Referring the same thing in different ways in the same report. 
  • Mixing reproduction steps with description, diagnosis, speculation or anything else. 

* Open the whotsit builder
* The wrong title is presented when I do this second time
* Press the OK button 

Split out the extra material: 

* Open the whotsit builder [A]
* Press the OK button 

[A] Second time around the title is missing “(2)”

  • Using descriptive adjectives to distinguish items. 

* Create one thingy
* Increase the X-parameter
* Create another thingy
* Move the thingy with the increased X into the panel for the first thingy 

Label them clearly instead. 

* Create a thingy (T1)
* Increase the X-parameter
* Create a thingy (T2)
* Move T2 into T1’s panel

  • “Edit the doodah in the back-end thingy then reload it” OK, say why, e.g. to simulate a particular back-end failure state.
  • “When I do the standard whotsit …” Standard to you, perhaps. Does everyone know what it is?
  • “Let’s do the first thing we decided yesterday.” Hello in there, other people read this ticket too. Give us some context, please.

Precisely is nicely. Loose is less use.
Image: http://flic.kr/p/6d3oYk