Tackshot
All guides

How to Write a Website Bug Report (Template)

“The checkout is broken” is a real problem report, and also a very expensive one. Before anyone can fix it, somebody has to ask which page, on which device, and what “broken” looked like. By the time the answers arrive, a day may be gone and the person who noticed may no longer remember the details.

A good bug report answers those questions the first time. It doesn’t need technical language or a long explanation. It needs a few specific facts.

What to include in a website bug report

A short, specific title. Say what went wrong and where. “Pay button stays disabled after entering a valid card” can be understood and searched later. “Checkout issue” can’t.

The page address. Copy the full URL. Many sites have several similar pages, and a bug can exist on only one of them.

What you did. List the steps in order, as if you were guiding someone through them. Include anything you typed or selected if it might matter.

What you expected, and what happened instead. The difference between the two is the bug. It’s also how a developer can tell a bug from a misunderstanding.

A screenshot with the problem marked. A plain screenshot of a full page still leaves the reader searching. An arrow, an outline or a pin tells them where to look. Black out personal details such as card numbers and email addresses before sending.

Browser, device and window size. Plenty of bugs appear only in one browser or at one screen width. “Safari on an iPhone” is already useful.

Any error you saw. If a message appeared, copy the wording or capture it in the screenshot. If nothing appeared, that’s fine too.

A website bug report template

Copy this into an email, a ticket or a chat message:

Title:
Page URL:

Steps:
1.
2.
3.

Expected:
Actual:

Screenshot: (attach it, with the problem marked)
Browser and device:
Error message, if any:
How often: every time / sometimes / once

A bad report and a good one

Here is the same problem reported twice.

Payment doesn’t work on the site. Please fix ASAP.

The developer now has to start with questions. Compare that with this version:

Title: Pay button stays disabled after entering a valid card

Page: yourshop.example/checkout

Steps: Add a lamp to the cart, go to checkout, enter an email address and card details.

Expected: The Pay button becomes active.

Actual: The button stays grey and nothing happens when I tap it.

Device: Safari on iPhone. Screenshot attached, with the button marked and the card number blacked out.

The second report takes a minute longer to write, and it can save a long exchange of messages.

Getting clear reports from people who aren’t technical

Clients, colleagues and visitors can’t be expected to learn a reporting process just to tell you something is wrong. These habits make their job easier:

  • Ask only for what they can answer. Most people can say what they tried to do. Few know their browser version, and they may not remember an error message that disappeared.
  • Give them one place to report. Feedback spread across email, chat and calls is easy to lose and hard to track.
  • Offer a short example. One good sample report teaches more than a long set of instructions.
  • Accept imperfect reports. A rough report is better than silence. Reply with one specific question instead of sending the template back.
  • Tell them what happened next. People report more when they can see that their last report led to something.

Let the tool collect the technical details

Most of the items above are facts a computer already knows. The page address, browser, operating system and window size don’t need to be typed by a person, and asking for them is where many reports stall.

A website feedback widget can collect those details and let the reporter mark up a screenshot directly on the page. The person only has to point at the problem and say what’s wrong. Our guide to website feedback widgets explains how they work and when one makes sense.

That is the problem we built Tackshot to solve. Visitors mark what’s wrong, and you get the screenshot and the technical details in one report.