How to Get a Usable Bug Report From Somebody Who Is Not Technical

Somebody who is not technical is not a worse reporter. They are answering a different question from the one you asked, and usually the question was the problem.

Almost every bug report form asks the same three things: what went wrong, the steps to reproduce it, and what you expected to happen instead. Each of those asks the reporter to do a piece of diagnosis. “What went wrong” asks for a cause. “Expected versus actual” asks them to know what the software was supposed to do, which is the knowledge they do not have and the reason they are writing to you. “Steps to reproduce” asks them to have been paying attention to a sequence that was not worth attention until it failed.

What a person can give you accurately is what they were trying to do and what they saw. Those are observations. Most of the rest of the form is a request for a theory.

The theory is the part to set aside

The costly thing in an untrained report is not the missing detail. It is the explanation, because an explanation arrives looking like an observation and you will spend the morning inside it.

“It logged me out” is a conclusion. Underneath it, the thing that actually happened is that a screen appeared with a sign-in form on it. That screen has at least four causes that have nothing to do with each other: the session genuinely expired, one API call returned a 401 and the client redirected on it, a cached page was served with the signed-out header, or they had a second tab open and signed out in that one. Start from “logged out” and you go to the session store. Start from “a sign-in screen appeared while I was in the middle of checkout” and you have the timing, the page and the symptom, and the session store is one of four places to look rather than the only one.

Weak

The site logged me out while I was paying.

Better

I was on the payment step and the page went back to the sign-in form. My basket was still there afterwards.

Nothing in the better version requires any technical knowledge. It is the same person, asked for what they saw instead of what it meant.

Words that do not mean what you assume

The vocabulary is shared and the definitions are not. These five do the most damage because both sides are confident they understood each other.

Crashed

The tab closed, the page went blank, a spinner never stopped, or the browser itself quit.

Froze

Nothing responded to clicks, or something was loading with no indication that it was.

Deleted

It is gone from the list in front of them. It may be filtered, on another page, in another account, or genuinely deleted.

Page

A URL, a tab, a modal, a step in a flow, or the whole site.

Error

A message you wrote, a browser error screen, or simply an outcome they did not want.

You cannot fix this by publishing a glossary, because nobody reads one before reporting a problem. You fix it by never asking a question whose answer is one of these words. “Did it crash?” has no useful answer. “What was on the screen when it stopped working?” has one.

Ask about the last thing that worked

The most productive question to put to somebody without the vocabulary is not about the failure at all.

Ask what they were doing immediately before, and ask whether it has ever worked. Both are things a person remembers without effort, and between them they bound the problem: the first gives you the entry point, and the second tells you whether you are looking at a regression or at something that never worked for this person in this situation. A feature that worked for them last Tuesday and not today is a different investigation from one they have never once seen work.

“Has it ever worked for you?” also does something the other questions do not. It is answerable with a yes or a no, so it almost always gets answered.

Ask for the screen, not for a description

A screenshot is the one artefact somebody untrained produces both reliably and accurately, because taking one needs no vocabulary at all. It carries things they could not have told you if you asked: the URL in the address bar, the width of the window, which account is signed in, the exact wording of the message, whether a banner was covering the button. Most of what you would have extracted over four emails is sitting in one image that took them five seconds.

So “could you send me a picture of what you are seeing” is worth more than any question you could write, and it is the easiest thing on the list to ask for.

The limit is worth knowing too. A screenshot shows the surface at one moment. It cannot tell you what the browser was doing underneath, and the failure often leaves no mark on the surface at all: a request that returned a 500 while the page carried on looking normal is invisible in an image.

What they cannot give you, and should not be asked for

Console errors, the network log, the browser version, the viewport size. These are the things that would actually shorten the investigation, and every one of them requires the reporter to open a developer tool and know what to look for.

Asking for them has a real cost and it is not the reporter’s time. It is that the request reads as a test. Somebody who cannot find the console now knows they have failed to help properly, and the next thing they notice is one they keep to themselves. The supply of people willing to tell you about a problem is small and entirely voluntary, and it is easier to lose than to build.

The honest answer is that this half should be collected rather than requested.

It will not write the title for you, and it cannot tell you what the person was trying to do. That part only comes from asking them, which is why the questions matter.

Ask one at a time

A list of six questions comes back with two answers and no indication which four were skipped. Worse, it reads as a form, and a form is a thing people put off until the weekend.

Send one question. When it is answered, send the next if you still need it. It feels slower and it is not, because the alternative is a long silence followed by a partial answer that generates three more questions anyway.

Keep in mind what you are interrupting. A bug report is the end of a chain of small decisions to bother: they noticed, they decided it was not their fault, they found out where to tell you, and they wrote it. Every exchange after that is another chance for the chain to break, and nothing tells you when it does. You just never hear back, which from your side is indistinguishable from the problem having gone away.

The questions, in the order to ask them

Four questions, none of which require the person to know anything about software:

• What were you trying to do?
• What did you see instead? If you can, send a picture of it.
• When was this, roughly, and what were you using at the time?
• Has it ever worked for you before?

If you get those four, you have the entry point, the symptom, a window to search your logs against, and whether it is a regression. That is enough to start, and it is more than most tickets written by people who do know the vocabulary.