How to describe a bug well?

Updated Apr 20, 2023 • 4 min read

Dear biologists. I’m sorry, but this is not a manual for you to find out how to describe new species.

This is a brief guide to our bugs-reporting flow which helps us to keep high quality in whatever we undertake.

We love web development, and we love functional, well-designed tools. It took us some time to find the perfect project management software, so we introduce you to JIRA that helps us to keep things on track.

Although we do our best in everything we take on, you never know if what you’ve already done is flawless. That is why we have a Quality Assurance team on board. They use JIRA to report bugs, developers come face to face with them (bugs, not the team ;)) and finally we get to the point causing extreme emotions… Accepting or rejecting tickets.

There is only one main rule in the world of testing: there is no mercy.

How to describe a bug? - our 3-steps long recipe.

First, we create a new story in JIRA, marking it as a ‘bug’.

A header is the essential part of a ticket - an appropriate header improves the work of both: developer, QA tester and project manager. It is also helpful for verifying the changes we’ve already done.

A meaningful header contains information concerning not only the bug itself (eg. wrong message), but also “time” or “situation” when you’ve noticed it (eg. trying to log in). Summing up, a ‘wrong message trying to log in’ pattern is appropriate
3. True story, bro. A story is the place where the fun begins. Not always the one written contains all the information we expect. It’s good not to forget to:

Write one story per one bug - the less complicated the story is, the easier it gets to solve the problem.
Use pictures - we use Jing in our everyday work. It’s pretty cool!
Don’t act like a film director - unless you are a nature-documentaries director, try to resist the temptation to make videos of the bugs you face. Use it only when a print screen is not enough.
Describe your experience in a simple way trying to avoid emotional comments - eg. Trying to log in, I see a pink elephant passing through the website is so much better than Who the hell has put here that ugly elephant?! Get rid of it ASAP you fool!
Use the AS IS/TO BE pattern:

AS IS/TO BE pattern

AS IS - describe what you see, eg. I see the content without the header
add appropriate picture
use arrows and autoshapes that Jing provides

TO BE - describe what you wish to see eg. I should see header and File menu above the toolbar.

After all, we save changes and leave it as it is in Icebox. This is the place, where bugs wait their turn. We release them into the wild by moving to backlog each week on developers’ meeting. Then developers start to fix them one by one, moving bugs automatically to Current box.

We love Jira and our developers love… ladybugs :) That is why they’re happy with Clients who are not afraid to simply use it the way we do.