← All writing

The clarifying question that gets an answer

Most issue threads do not die at the report. They die at the first reply, the one asking for more information, which sits there gathering nothing until somebody closes it as stale two months later.

The usual reading is that the reporter lost interest. Sometimes that is true. Far more often the question was unanswerable, or expensive, or looked like a form, and the person meant to come back to it once they had time, which is a thing nobody ever has. Asking is easy. Asking so that a reply arrives is a separate skill, and it is mostly four habits.

One question, not five

A list of five questions does not get five answers. It usually gets none, because it reads as an assignment rather than a conversation, and because the reporter cannot answer the third one, which means the whole thing now requires effort they will schedule for later.

One question gets answered because answering it is a thirty second job that can happen from a phone. Then, if you need it, the next one gets asked, and by then you know something you did not know before, so it is a better question than the one you would have written up front.

Reads as a form

Thanks for the report. Could you provide: browser and version, OS, steps to reproduce, expected vs actual behaviour, console output, a screenshot, and whether this happens on other accounts?

Reads as a question

Thanks. Does this happen on every export, or only on the large ones?

This is the same reason issue templates get filled in with N/A. Asked all at once, questions become a toll, and people pay tolls as cheaply as they can.

Ask for what they have, not what you want

The best question can be answered from memory, sitting still, without opening anything. The worst one asks the reporter to reproduce a problem they have already escaped from, on your behalf, for free.

"Can you give me reproduction steps" is a request to do the investigation and write it up. "Were you creating a new invoice or editing an existing one?" is a request to remember. The second one gets answered on the same day, and half the time it is enough.

Some information genuinely does require work: a log file, a HAR capture, a retry with a flag enabled. Ask for those too. Just ask for them second, after the free questions have narrowed things down, and after the reporter has already had one small satisfying exchange with you.

Say why you are asking

A question with a visible purpose gets answered at a completely different rate to a bare one, and the reason is not politeness. It is that the purpose lets the reporter give you something better than what you asked for.

No purpose attached

What version are you on?

Purpose attached

What version are you on? There was a change to how exports are batched in 4.3 and I want to know which side of it you are on.

Faced with the first, the reporter answers "4.2" and stops. Faced with the second, they are quite likely to answer "4.2, but our staging box is on 4.4 and it does it there too", which is the sentence you were three questions away from getting to.

There is an uncomfortable corollary. If you cannot say what you would do differently depending on the answer, you do not need the answer. That is most of what a template asks for.

Offer options where you can

People who will not compose a paragraph will happily pick from a list, and a list also teaches them what kind of answer is useful. It converts an essay question into a multiple choice one.

Answerable in one word

When you say it does not save: does the page show an error, does it sit on a spinner, or does it look like it saved and the change is gone when you come back?

Three options, one of which is almost certainly right, and the reporter can answer with a single word. It also quietly rules out the fourth possibility, which is that you and they meant different things by "does not save" and were about to spend a fortnight finding that out.

Offer options when you have a real hypothesis. Do not offer them when you do not, because a bad list steers people towards a wrong answer they would not have volunteered.

The last one is the hardest

All four habits point the same way: move the effort from the person who has the information to the person who wants it. That is the right direction, and it is the opposite of what a busy team naturally does, because the busy team is optimising its own time and the reporter's time is somebody else's budget.

It is a real trade. Writing one good question takes longer than pasting seven mediocre ones. What you buy is a reply, which is the entire point, and which the seven were never going to produce.

WhatProblem asks these questions for you

It reads new GitHub issues and asks what is missing, in the issue thread, before anyone on your team has to.

Install from GitHub Marketplace