How to ask questions well, asynchronously

I’ve been writing and reading a lot of questions on camera and programming forums recently, which got me thinking a lot about how to write questions well.

Why should you care about this?

The most direct answer is “well written questions solicit better responses quicker”, but my motivations are different to that, so it’s maybe more instructive to talk about those directly.

I developed a care for writing questions well from two places:

• StackOverflow! When I started programming, it was still used for asking questions, and wasn’t just the first hit on Google. If you wanted help, you had to be precise about your problem, and people could quickly get snarky and unhelpful – especially for vague questions. The thought of an Internet Stranger thinking I was a lazy jerk was a big motivator to write things up thoughtfully and carefully¹.

• Working asynchronously! My last job was remote and all of my teammates were on time zones 6+ hours different from mine. If my colleagues and I were working together on something, and wanted to be able to work effectively while people were offline, we needed to be able to communicate precisely. The productivity of my colleagues turned out to be a huge motivator.

The hardest thing about communicating asynchronously is that you need to be extremely careful to make sure that your meaning comes across clearly. The cost of getting it wrong is the wasted time waiting for a response which says “Hey! I didn’t understand your question”. Therefore, it makes sense to spend time adding redundancy, context, and clarity to the question you’re asking to make sure that your intention is clear.

The high level idea here is that investing a little extra time in your communications can save both you and your communication partner time and energy, and make them feel respected and appreciated in the process. I think it’s especially important in the case of online forums, where the people answering questions are often doing it out of goodwill, and they’re sometimes thinly-stretched open-source maintainers. Make it easy for them to help you.

Asking questions well

Let’s look at an example! Here’s a question I asked on the Hugo forums the other day:

Are the assets produced by calls to js.Build cached? (1)

To make the question more concrete, I have a partial named head_includes.html (2):

{{ $opts := dict "targetPath" "js/main.js" "minify" true "target" "es2015" }}
{{ $mainJs := resources.Get "js/main.js" | js.Build $opts }}
<script type="text/javascript" src="{{ $mainJs.RelPermalink }}" defer></script>

This is included on every page on the site, and I wanted to make sure that the JS build is only running once per site build, rather than once per page (3).

Some limited profiling (with hugo --templateMetrics) and swapping between including this partial with both partial and partialCached results in no difference in build performance, which seems to suggest that the js.Build is cached, but I wanted to check :) (4)

My strategy with this format was:

• Directly and concisely ask the question (1). This allows readers to anticipate where the rest of the text is going to lead them, and hopefully makes it easier to frame the rest of what I’m asking within that context.

Everything after that exists to add additional context – to hedge my bets against miscommunication. Some techniques I’ve used here are:

• Including a concrete example (2) of the context in which my question applies. This allows readers to verify that I haven’t made any obvious mistakes where I’ve asked a question that I thought was relevant to what I’m doing, but wasn’t. In this case, it’s a code snippet! If I was talking about a camera problem, I’d talk about the settings I’m using and the conditions I was taking photos in.
• Including my end-goal (3) – in this case, “I want my build to stay fast”. This helps avoid the XY Problem, and is especially important when I’m new to a technology, or to a specific domain – in those situations, there’s so much that I don’t yet know that it’s likely I’ve found a suboptimal path to a solution.
• What I’ve tried so far (4). In this case, I think I mostly did this out of that pesky “desire to not look like a lazy jerk on the internet”. But, for issues that are more complex, or might require some debugging, it’s helpful if you include this so that people can reproduce your problem if required.

What about when you’re answering questions?

Even if you’re a pro at asking questions, you can’t possibly know everything about a scenario – otherwise, you wouldn’t be asking for help troubleshooting! It’s therefore important to be compassionate and similarly thoughtful when you’re answering a question.

Sometimes you’re ~80% sure that you know the answer to what someone is asking, but all of the background and assumptions aren’t clearly stated. You could just ask clarifying questions, but this adds a back-and-forth cycle to the communication. You could also go ahead and answer the question directly, but then you’re leaving all the room for the miscommunication in the middle.

In situations like this, I prefer to answer the question, but state all the assumptions I’m making that allow me to arrive at the conclusion. Here’s another example from the Hugo forums:

I’m guessing that you’re using Github Pages for hosting, as per Host on Github. (1) Let me know if those assumptions aren’t right! (2)

The setting you’re looking for is to make the repository private but I don’t think that works with Github Pages. (3)

I guess this repository would contain the output of Hugo, i.e., the generated site. Is that right? If so, is it really a problem whether people can see it or not? People would also theoretically be able to download these files directly from your website using a tool like wget – unless your website has secret pages that should only be accessible by guessing the URL. (4)

Again, there’s four parts to this:

• State assumptions (1)! Explicitly outline the circumstances that make your answer valid or not. The assumptions in this example are based on information provided in the question, and I’m echoing the language that the asker is using.
• Invite the asker to challenge those assumptions (2). I’ve tried to convey through my tone here that it’s ok if there’s a miscommunication – I’m not going to blame them if I’ve made the wrong assumption. If I had cared about that, I should have asked the clarifying question up-front instead ✨
• Answer the question that was asked (3). I think you should do this even if the question doesn’t help the asker towards their root concern, because it makes the asker feel like you’re taking them seriously. In cases where the question asked is less relevant to the root concern, though, I put in less effort – just a link to some documentation or a high level idea works.
• Address the root concern (4) – in this case, the asker was concerned about the security implications of what they were doing, and the answer was “there aren’t any, you don’t have to worry”.

I could have answered this question by just jumping straight to the answer (4), but I think this would have been much less helpful – the extra 5 minutes of effort required to write everything else convey that I’m engaging with the person seriously, that it’s ok that they don’t know this thing, and that I was happy to help. Especially in public forums, where every action you take is effectively modelling behaviour for the rest of the community, I think taking the extra 5 minutes to communicate both precisely and compassionately can help to make the entire community more welcoming.

That’s it!

Here’s the cheat sheet version:

When asking questions:

• Lead with your actual question, succinctly
• Include a concrete example of the context in which your question applies
• State your end goal, i.e. what you’re actually hoping to achieve, and what your question is aiming to move you toward
• State what you’ve already tried.

When answering ambiguous questions:

• State any assumptions you’ve made to resolve ambiguity
• Invite the asker to challenge those assumptions
• Answer the question that was asked
• If that’s different from the root concern, address that too.

Above all, be willing to invest time in removing ambiguity from your communications. It is effort, but it pays off.

These are the tools that I use when communicating asynchronously, but I’d bet that they vary a lot from person to person! I’d love to hear what works for you too, and you can get in touch with me here. ✨