Hi there! My name is Dave and, as a Support Engineer at FreeAgent, I spend a lot of my time talking to our customers, our support agents and our software developers about the behaviour (and occasional misbehaviour) of our product. Fixing a product issue is an incredible opportunity to delight your users and show that, when push comes to shove, you stand by your service and your customers. During my years in this role, I’ve come to value the power of clear, accurate and meaningful communication, which allows teams to quickly understand and discuss issues to be addressed without any tedious back-and-forth. In this blog post I’d like to share some tips for writing a stellar issue report that will help your teams to communicate effectively and continuously deliver on your product.

It’s all in the name
When your bug report appears on someone’s screen, the issue title is likely the first thing – possibly the only thing – they’ll see. Your issue titles need to describe the visible problem; what does the end user see when they’re bitten by this issue? In my experience, most product managers want to initially understand the ramifications of an issue before digging into the nitty gritty – that comes later! The customer-facing impact is often the only piece of information available to a support engineer when they first pick up a support request – if you can search for the symptoms and find an existing issue report, you’ve just saved yourself a chunk of work.

Your issue titles need to describe the visible problem; what does the end user see when they’re bitten by this issue?

Write for a wider audience
Most technical documents are written with a specific audience in mind. Issue reports, on the other hand, tend to be consumed by multiple audiences from various teams in a business. As an example, when I raise a bug report in FreeAgent, it’s usually initially seen by my support engineering colleagues and then moved to a weekly triage meeting held by our product managers. It will eventually be assigned to an engineer, who may or may not be familiar with the problem. My advice is to start with the big picture and provide more information as your report develops. Begin with a meaningful title, continue with precise steps to reproduce and end with any extra relevant information you can share. A reader can always stop reading the page once it becomes too detailed, but if you interweave high-level and low-level details, you make it harder for the reader to be savvy with their time and attention.

…start with the big picture and provide more information as your report develops.

Breadcrumb engineering
It’s amazing how an issue can flow through different channels as it meanders from support, through product management, into engineering and (hopefully) out into the big wide world as a bug fix. I’m a big believer in the “breadcrumb” approach to engineering; you never know when a colleague will wander into a conversation, so you should leave a trail of breadcrumbs back to a single source of truth. If customers contact you to report a bug, link their support request(s) and related issue report(s) together. If a bug in your product triggers an alert in your error tracker, link the tracker to your incident report so engineers can see it’s a known problem – and maybe even fix it. If you have an interesting conversation in Slack while discussing a fix, have that conversation in a single thread and link back to that thread from your issue tracker.

I’m a big believer in the “breadcrumb” approach to engineering… leave a trail of breadcrumbs back to a single source of truth.

Pulling it all together
Here’s an example issue report for a genuine bug we found in our transaction search functionality.

A product manager is able to understand the customer-facing issue simply by reading the title. A curious engineer can reproduce the problem in 2 succinct steps and, using the background information at the bottom of the page, it’s even possible to estimate the complexity of a fix without reading a line of code. Thanks to this well-written issue report and our weekly triage process, this issue went from a support ticket to a deployed fix in less than a week. Now go forth, document and squash those pesky bugs!

Photo by Alain Wong on Unsplash