Lin ran the online ordering page for a small furniture workshop, and one Tuesday morning an email landed from the owner: “Checkout is broken, please fix.” Lin spent forty minutes clicking around, found nothing wrong, replied with a polite question, and then waited most of the afternoon for an answer. By then two customers had already phoned the workshop to complain. This story is a gentle way to explain what a good bug report looks like, and why asking for technical help clearly is less about being technical than about being considerate.
What is a bug report, really?
Strip away the jargon and a bug report is a short message that says, “Something did not behave the way I expected, and here is enough information for you to see it too.” The last part matters most. A fix is only possible once the helper can watch the problem happen on their own screen. Everything you write should make that moment easier.
The five parts of a message that gets results
After the checkout incident, Lin and the owner sat down and built a simple template. It has five lines, and each one answers a question the helper would otherwise have to ask.
- What I wanted to do. “Order a walnut shelf and pay by card.”
- What I tried. “Added it to the basket, entered my address, pressed Pay.”
- What I expected. “A confirmation page and an email.”
- What happened instead. “The button greyed out and the page stayed still. No message appeared.”
- The smallest example. “It happens with a single item and a UK address, but not when the phone number field is left blank.”
Notice what is missing: opinions about whose fault it is, long histories, and capital letters. Lin was struck by how plain the template felt. It was just a polite way of showing your homework.
Why the “smallest example” is the secret ingredient
Imagine a doctor’s receptionist trying to find a lost file in a cabinet of ten thousand folders. “It is somewhere in there” does not help. “It is a blue folder filed under the second letter of the surname” does. A minimal example works the same way: it shrinks the haystack. In the workshop’s case, narrowing the failure to the blank phone-number field pointed Lin to a form validation rule within minutes.
If you cannot find the smallest example, you can still help by listing what does work. “Paying with a gift voucher goes through, paying by card does not” is already a strong clue, because it splits the checkout into two paths and tells the helper to look at only one.
Showing your attempts is not a weakness
Some people feel embarrassed to admit they have already restarted things, cleared saved data or tried another browser. They should not. Those steps rule out the obvious causes, and the person helping is grateful not to repeat them. Writing “I already tried a second browser and the problem is the same” saves one entire round of messages.
Where practitioners go to see good examples
When Lin wanted more practice, a friend pointed to Debug School, a site where members publish articles about DevOps, DevSecOps, SRE and other operations topics for fellow practitioners and learners. Lin skimmed a few posts and spotted the same habits as the template: start with the situation, show the evidence, finish with something specific to answer. It was reassuring to find that experienced engineers write that way too.
Questions before the project even starts
Good questions are not only for emergencies. They are also the best tool when you are deciding what to build in the first place. If your own business is weighing up a new site or tool, the checklist in this guide to interrogating a custom software idea early makes a handy partner piece, since it shows how many nasty surprises vanish when the right person gets the right questions on day one.
The workshop later adopted the same habit when choosing improvements. Before approving any change, the owner asked the five lines of the template in reverse: what do we want, what have we tried, what do we expect, what could go differently, and what is the smallest version we could test first. The result was fewer costly surprises and calmer meetings.
Small habits that make a big difference
- Quote messages exactly. Paraphrasing an error loses the one detail the helper needs.
- Mention the time. Logs are time-stamped, so “around ten past nine” is enormously useful.
- Attach one clear screenshot. Crop it to show the relevant part, and say what to look at.
- Keep one problem per message. Mixing three issues makes every one of them harder to track.
- Say what changed recently. A new plug-in or a freshly updated setting is often the culprit.
What happened to Lin?
Over the next few months the workshop’s support emails changed shape. Instead of “it is broken”, Lin received short messages that read almost like lab notes. Problems were fixed in a single exchange more often than not. When a repeat problem appeared, the old messages made it quick to check what had been tried before. Lin even started tidying repetitive work as a result, using ideas similar to those in a practical piece on trimming manual steps from daily workflows, because clear messages revealed which tasks kept coming back.
The lesson is a human one. A clear question tells the other person that you value their time and trust them to help. In return, they usually give you their best effort. Write your next request as if you were handing a stranger a neatly labelled box, and see how differently the reply feels.

