James Thinks
writing is a kind of thinking
"My client has a problem with a file"
The above is the full text of an actual bug report received by a former colleague of mine. She could've contacted the person who raised the report asking him to tell her "Which client?", "Which file?", "What kind of problem?", "Which system were they using?" or any other number of essential pieces of information. As my colleague had a list of bug reports numbering three figures, instead she shrugged and moved on to a report with better information. No doubt the person who raised that report was also very busy, but they only wasted their own and others' time by raising such an unhelpful report. I think that when reports like this are commonplace it suggests that there are some misunderstandings about communication between developers and users.
Can't the developer just ask me for more information?
Perhaps the user whose client had a problematic file was only intending his very terse report to start a conversation. That's natural enough. When someone visits the doctor and says, "I feel unwell" they don't expect a diagnosis straight away, rather a series of questions from the doctor to gain an insight into the patient's illness. That's fine when both parties are sitting next to each other discussing it. When they are working in different offices, maybe different time zones, then it becomes a painfully slow process. If a developer asks for more information and the user is in a meeting or asleep, they can't simply sit around waiting for a response, they're forced to work on something else, with the associated cost of context switching. Sure, sometimes further questions may still be needed, but the user can jump-start that process with a clear report.
Surely the developer knows what I mean?
Users may have the impression that the software engineer knows more about the software than they do. Software engineers may spend lots of time looking at code but much less, if any, time using the software. Users are the experts at how the software works as they often use it day in and day out. Their insights about how it works and how it should work are invaluable to developers. Sadly they are often left out of bug reports on the assumption that developers already know everything that users know.
The developer must be aware of this bug already!
A bug report might be seen by some as an official way to force a developer to fix an issue that they already know about. Again, this isn't usually the case. If a developer discovers an issue, they'd normally raise a bug report for it, even if they didn't have time to fix it immediately. Everyone who raises reports should also be able to search the list of bugs to see if anything similar has already been reported. If the bug isn't listed in the database, it's likely that no one else knows about it. If it is, then there's no point creating a duplicate. Raising a duplicate report only creates confusion. Instead the user should be able to update the existing bug report perhaps to say, "This is also affecting client X" or "I have observed the issue on Sundays as well as Bank Holidays.". This extra clue may make fixing the bug easier.
What does a good bug report look like?
If you write helpful bug reports, with a few minutes of your time you could save the developers hours, if not days, of their time.
You do want this fixed quickly, right?
Where developers can choose what to work on next, they'll naturally prefer quick wins. Thorough yet concise bug reports focus the developer on a solvable problem. Vague ones feel like being asked to find a needle in a field full of haystacks.
Now I've lectured you on why it's important to write good bug reports, here are my suggestions of their most important features. This list is generalised. For certain projects there may be additional essential information.
- Search for any similar bug report - If found, optionally add to it. Do not create a duplicate. If unsure, link to the original.
- A short, descriptive title - Enough to distinguish it from similar issues. Probably 4-10 words.
- Include all relevant details - e.g.: Server, product, client(s) affected, file type, time of day, web browser version. Make that haystack smaller!
- Steps needed to reproduce the issue - A developer may not know how to reproduce the issue. If they can't do that they probably can't fix it and definitely won't know whether they've fixed it.
- Expected result - Make it absolutely clear what you wanted the software to do. e.g.: "Display the total number of rows the uploaded file has at the top of the page."
- Actual result - Again this ensures clarity when compared to the above. e.g.: "Null is displayed and the menu-bar disappears."
Those are the essentials. If you have time to investigate further then any other clues you can add are a bonus. For example, insights like these may also be helpful and speed up the process of debugging.
"This only happens on days immediately following bank holidays"
"It worked on Friday 4th, but failed on Monday 7th"
"It only affects admin users".
I hope my suggestion helps users to get bugs fixed more quickly and developers to enjoy fixing them more.
James Bradbury
I write about whatever is on my mind. I do so mostly to help me think more clearly. If other people find it interesting that's good too. :-)
Users may have the impression that the software engineer knows more about the software than they do.
If you write helpful bug reports, with a few minutes of your time you could save the developers hours, if not days, of their time.