User acceptance testing is only as good as the problems it surfaces. A lot of times this means clicking through web apps ad nauseam to find bugs on paths less traveled. Other times it might mean building a suite of automated tests in Cypress. Inevitably, UAT means reporting bugs in the product. Sometimes explaining a bug can be just as difficult as finding the bug itself.
Writing high quality bug reports is a time-consuming, manual process. In this post we'll give you an easy to use templates that can be used across many bug tracking systems. We'll also show you how User Bug Report can automatically generate beautiful, high quality bug reports for you.
Platforms / Formats
We're going to use the same basic template and apply it to the most popular bug tracking systems. If you want to skip ahead to your platform of choice, click on one of the links below:
- Markdown (super minimal)
- Markdown (detailed)
- User Bug Report
- Pivotal Tracker
- Microsoft Excel
- Google Sheets
- Microsoft Word
- Google Docs
A great defect report means getting the details right.
The Absolute Minimum
This the "MVP" bug report. I'd recommend going into more detail but this template might be all you need if you're working on a small, close-knit team.
- Title: Obvious beats eloquence. Go with something straightforward. Remember that often times your team members might be non-native speakers of your company's operational language. So bear that in mind for word choices.
- Description: Again keep it short, sweet and to the point. Some reports will require a lot more explanation than others—think an incorrect button color vs. an inconsistent data issue. Again, remember your non-native language speaking colleagues.
- URL: Provide the full URL to the page where the issue occurred.
- Screenshot/Video: A picture is worth 1,000 words. No different here. And it's no surprise that engineers rated this the #1 most helpful part of a bug report in our survey.
- Logs: Network and console logs provide clues to what might have happened. In the event of a difficult to reproduce issue, logs are invaluable.
Here is a simple markdown template that can be used in any tool that supports markdown.
Here's what a rendered version of that template would look like.
More Helpful Data
- Application Version: Simple yet very useful. Include the active version as either a SemVer, git hash, or whatever nomenclature your company uses.
- Network Requests: Including both succeeding and failing network requests will make an issue easier to debug.
- Browser Metadata: Browser type, screen size, pixel ratio—these are all very useful for debugging front-end issues.
- Device Metadata: Similar to browser metadata, device info helps identifying issues across devices.
- Local Time: The time the event happened with the local time zone.
- User ID: Don't forget the lowly user id. This provides engineers with an account to use in order to replicate a problem. You could go a lot deeper here by providing user data specific to your app (this will be very company specific so I'm not going to attempt to generalize it here).
- Custom Data: A bit of a catch all, but adding in data that's custom to your application is typically helpful. Things like application state, page sequencing, and user data all fall into this category.
Network request logs often prove essential to debugging front-end issues.
Detailed Markdown Template
Here's a more detailed version of the first template. Again, it's using standard markdown syntax. You can use this anywhere markdown is supported.
User Bug Report
This form might seem overwhelmingly tedious to fill out for every single bug report. Fear not—there is a much better way than wasting your time computing the local time in Texarkana, TX.
Time for a shameless plug. Our product, User Bug Report, automates the boring, laborious work of creating a high quality bug report. All you need to do is write a title and description and you're done. And the best part—it works with your existing tools. We integrate with your existing bug tracker so your bug report is automatically sent to JIRA/GitHub/Trello (among many others) formatted and with all of the data we've outlined above.
An example bug report generated for GitHub by User Bug Report.
Depending if you use a hosted or cloud version of Jira, you might need to adapt this template. However, most Jira issues allow you to use a markdown-ish language to create issues.
Jira: The tool folks love to hate.
Trello supports markdown in the description of each card. You can also attach images and other files to each card as well.
Trello: The $425 million TODO list.
GitHub has its own flavor of markdown that is a superset of regular markdown. You can also add images and other files to issues as well.
GitHub: The sources of all my issues.
GitLab also has its own flavor of markdown—again, also a superset of regular markdown (it's like they're just copying GitHub or something). Same as GitHub, you can add additional files to issues.
GitLab: Like GitHub, but a little more purple.
Monday.com: Maybe Mondays aren't so bad.
Asana has it's own strange rich text editor that combines standard markdown syntax with completely custom features. You can use RTF to get what you want 👍.
Asana: The TODO list that IPO'd.
Clubhouse had the best markdown/RTF support of any of the bug trackers we tried. I also thought the styles were quite nice. I might have to give this one a try for more projects!
Clubhouse: Looks (head) banging!
Before Trello there was Pivotal Tracker. I never quite understood the right-to-left thing (I know, I know it's more effecient or something). But it paved the way for the "drag and drop card-based" bug trackers.
They support markdown--though I must say it could use a styling update.
Pivotal Tracker: The first of its kind.
Excel is ubiquitous and it can make a nice way to do basic templates. You probably won't run your entire dev tracking system in Excel (though you probably could!) so this is best used as an attachment in another system such as Jira.
Excel: Maybe not sexy, but it's everywhere!
Excel's web-savvy cousin, Google Sheets! Same rules apply here. You could probably track everything in a Google Sheet...but you probably shouldn't.
Google Sheets: What can't you do with it?
Similar to Excel, Word is another egalitarian way to do basic templates. Again, you'll want to use this in conjunction with another tracking system.
MS Word: Tried and true since 1983.
Just like Word but on the web. Same story, you'll want to uses this in addition to a dedicated bug tracking system.
MS Word: Tried and true since 1983.
Before you go
Hopefully you found this post helpful. If you're interested in learning more about User Bug Report, subscribe to our newsletter or visit our website: https://www.userbugreport.com/.