Effective Bug Reporting

Peter Naulls
Nov 27, 2019 · 6 min read

“It doesn’t work”, and other ineffective bug reporting techniques in an age of agile development.

Image for post
Image for post

When I started my software career in the late 1990s, the ideas of bug reporting weren’t new, but in the 20 years since, much has changed with agile development, newer software systems and ideas about tracking software and tasks.

In particular, there was the following seminal classic by Simon Tatham back in 1999:

Even now, (or perhaps, especially now), Simon’s comments remain relevant, and this has always been the article that I’ve referred people to. However, after years of software development, and working closely with QA engineers, and with reference to newer reporting systems, it’s time to make my own version, especially since I haven’t been able to find anything that is as comprehensive as what I want to articulate here.

What is a bug?

First, I’d like to turn the paradigm on its head and explain that when I say “bug”, I’m definitely not limiting the meaning to a software fault of the kind we have traditionally thought about.

In some reporting systems, it’s called a “story”. This is deliberate, and in keeping with what I’m about to assert. To this end, you may interchange “bug” with “story” or “task” or whichever nomenclature your systems or development style uses.

Here are some examples of what a bug or story might be:

  • A report of a fault

This is list is naturally incomplete.

Here’s my point — a bug or story is something to be done — it describes the current situation and what the outcome might be. Put differently, it could describe every single step of software development — the specifications to write, testing to be done, documentation to write, faults to fix, etc etc. Now, to seasoned software engineers, this is probably obvious, but for many engineers, I know it’s not necessarily so, so I’d like to repeat it one more time:

A bug/story is a description of a task to be done and tracks its life cycle.

Clear on that? Good. Then the rest should make sense.

What a bug isn’t (In my opinion)

  • An observation without conclusion or task. “The sky is blue”.

But they can be…

  • To Do lists (as long as there is completion or follow on)

Bug Reporting Systems

Here are some of the common bug reporting systems around:

  • Bugzilla — the old standby, and much in evidence when Simon wrote his piece, but not so much used now.

Why bug reporting systems can be bad

There are lots of reasons bug reporting systems can be intrusive or irritating. Like much, it’s a matter of balance.

  • Excessive emails — systems like Jira can produce extraordinary numbers of emails if you look at them the wrong way. If you subscribe to everything (as I’m personally wont to do), then it’s a lot. Most engineers simply want to see the stuff they’re doing right now, and find the rest distracting.

The Importance of Titles

“A good bug title states something which is true, but you want to be false”.

Not my quote, but a good rule of thumb. Of course, not all bugs fall into this category, but an effort here pays dividends upon review of a bug much later.


  • “The application shows the measurement to too many decimal places”


  • “Network issues” (Really?)

The point here is that poor titles are misleading, cause miscategorization and misunderstanding. So, your aim for a title should be as terse as possible, but also as accurate as possible.

What a good report might have

  • Short but descriptive title — As above

Other guidelines

  • Pictures are good! Unless it’s text, then cut and paste is much better, since that means search ability.


For practice; come up with some bugs relevant to your situation. Make sure it follows the guidelines I’ve outlined.

Have a peer review it, who’s familiar with the problem:

  • How does the title read?


Not everything here works for everyone. But I think most of it does. But good guidelines adapt like good bugs. I expect what I wrote here won’t be as correct as it was in a few years, just as Simon’s is no longer complete.

Good luck!

Adventures in Software Development

Programming, Software and Lessons Learned.

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store