Help us to help you – good questions beget good answers

Composing good questions is important and will help your fellow community members answer them more easily. This post suggests some key aspects of a good question, and also gives some tips on how to respond.

This post is available via the shortlink: bit.ly/help-us-to-help-you.

The concept of Q&A in online communities goes back as far as I can remember, way before the days of the Web, even before the days of the Internet. And what’s held true all this time is that the availability, quality and usefulness of the answers relates directly to the quality of the questions. Ask a question well, and you’re more likely to get engagement from fellow community members and they’re more likely to try to, and be able to, help you.

Almost 6 years ago I wrote a post “Help  us to help you – Share Your Code” which is still relevant today, but I thought this new post might be more appropriate with new information that will hopefully help us all build a corpus of Q&A content that is easy to add to and useful to refer to. Then and now I’m primarily referring to questions related to development topics, but the sentiments are relevant beyond that too.

Asking questions

Here’s what a good question looks like:

• It describes the context clearly, both via an initial sentence or two and via appropriate tags
• Relevant code is shown in-line in the question, appropriately formatted, so that the reader can see the code directly in the same flow as trying to understand what is being asked (all unnecessary code and comments have been removed to make the code shown as small as possible)
• The question has a link to a complete reproducible minimal scenario that has been put together specifically to demonstrate the problem, and this scenario is easily cloneable and runnable by the reader (see the “Help  us to help you – Share Your Code” post for more information on using e.g. JSBin, GitHub / Gists or other mechanisms*)
• If a diagram or screenshot would help with explaining the scenario, that would be provided too, also in-line
• You’ve described what you’ve tried so far, and what the results of those efforts have been
• Any additional detail you’ve been subsequently asked to provide has been edited into the original question

(*In the case of CAP related questions, you can consider using the issues section of the CAP Community GitHub repo at bit.ly/cap-com)

While I’ve described some “Do”s, I’ll list some “Don’t”s which should be obvious but are probably worth listing enumerating here:

• Don’t provide code that is not properly formatted – it just makes it hard for the reader to comprehend; use the code formatting features appropriately
• Don’t provide code as attachments to the question – that’s even worse than providing unformatted code as it places the onus on the reader to take pains to download the attachments, load them into an editor, work out what’s what, and then continue reading
• Don’t add further information anywhere else (except for the cloneable and runnable scenario) – if you need to add more information, do it in the original question by editing it
• Unless you are directly answering your own question, don’t use any of the “Answer” sections – if you are responding to a comment, either do it with a further comment or (if appropriate) update your question content

Responding to questions

There’s an art to responding to questions too, here are some thoughts on that (note that I wrote “responding to questions”, as there’s more to it than just “answering”):

• If you need the person asking the question (often referred to as the “Original Poster” or “OP”) to clarify something or otherwise improve or provide more detail to the question, use a Comment to ask them to do so (i.e. don’t use an Answer)
• In general, use Comments to correspond with the OP and other participants, *unless* you’re answering the question (in which case of course use an Answer)
• If you need to show code in your answer, follow the same guidelines as for asking questions – make sure it’s formatted appropriately, and either in-line in the answer (that’s the ideal scenario, not the whole solution, just the relevant parts) or linked to elsewhere

Upvoting and downvoting

There’s a reason we have upvoting and downvoting buttons. If you think a question or answer is a good one, then upvote it with the up-arrow. It will help the author of the upvoted item understand that they provided something of value. If you feel you should downvote a question or an answer, do so but always provide a reason, as a comment, as to why you downvoted it.

If you’re the OP and someone’s provided an answer to your question that’s appropriate, ensure you mark it as such.

Summary

Hopefully the advice in this post is useful. Some of it is practical, some of it is related to etiquette. I’ll leave it up to you to work out which bits are what. It’s not polite to ask a question “lazily”, by not stating the problem clearly, not showing what efforts you’ve made to solve it, and by not making it as easy as possible for your fellow community members to help out.

Help us to help you, and let’s do our best to build a valuable database of knowledge through the next decade.

For a more in-depth set of guidelines, see “Writing the perfect question” (thanks Frederik Hudak for the pointer).

Examples

As and when I come across what I think are nice examples of good questions, I’ll post links to them here.

• CAP: Custom logic not receiving query parameters from Krishna Kishor Kammaje

Updates

2020-01-15 Added Examples section