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:

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:

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

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:

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:

When answering ambiguous questions:

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. ✨

  1. This culture helped me to grow in this specific way, but it’s problematic for other reasons! The problems came to a head in 2018, with a post from StackOverflow titled Stack Overflow Isn’t Very Welcoming. It’s Time for That to Change, and they’ve been working on it since, but it has not been smooth sailing, and based on some personal recent interactions on the site, I still think they have a way to go on this. ↩︎