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.
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.
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).
As and when I come across what I think are nice examples of good questions, I’ll post links to them here.
2020-01-15 Added Examples section
Thanks for this short but concise post!
Maybe I would like to add: "eliminate all unecessary comment lines from your sample code".
Thanks Enno, yes. I tried to convey this with “Relevant code is shown in-line …” but I’ll add a reference to unnecessary comments explicitly … Done!
I think there are many other important “bad” behaviors (people asking simple questions because they didn’t search, people who searched but don’t explain why the results don’t answer their question, people who answer only by giving links – should be comments, all upper case, OP should do a feedback, hijacking other questions especially old ones, etc., etc.) Maybe it’s worth creating a git project for a clean forum (clean question, clean comment and clean answer), like we have a style guide for “clean code“, with one file for each behavior so that it’s easy to link only the reported behavior, and people can enrich it. The current rules of engagement are not enough (to be compared to the rich StackOverflow help).
"If a diagram would help with explaining the scenario, that would be provided too, also in-line" - may be it's better to use "screenshot" instead of diagram!
Good spot, I've added screenshot too. Thanks!
May be after ...in-line can be added:
(using "Insert Image" button)
Also: "Relevant code is shown in-line in the question"
To be "Relevant code is shown in-line (using "Insert Code" button) in the question"
Not all users understand "in-line" 🙂
Then this would be a good chance for them to learn what it means 🙂 I always take the opportunity to embrace new words, both in my native language and the one(s) that I'm trying to adopt as second languages.
P.S. And one thing to add:
Always provide detailed version/SP information about system used.
If you're looking for more guidance, Jon Skeet (known for answering pretty much every C# related question ever to exist on stack overflow) has a blog full of similar tips:
Thanks Frederik! I've added this link to the end of the post.
If anyone is looking for more guidance (and it's a big "if" 🙂 ) then we have plenty of material on this right here on SCN.
This one could be the earliest (2010) blog on the subject. "Former member" author was an ABAP forum moderator who since retired. I frequently send this link to those who seem to struggle with the questions.
Then this one is from 2012, around time when SDN became SCN. There were more of those, I think, but didn't have time for a thorough Google search. More recently, in 2018, Bärbel Winkler chimed in with her thoughts on this too.
And back in the days, the moderators Juergen Lins (who since left SCN) and Matthew Billingham (still with us, thankfully!) wrote on this subject from the moderation perspective here and here. (This was back when the questions were moderated.)
Sadly, those who need to read these blogs never do. ¯\_(ツ)_/¯
This blog does highlight one new challenge: using answers and comments. I still feel this was an unnecessary addition and too many times I see many folks continue struggling with this structure. And since the hierarchical comments were disabled, conversing within a question has become even more cumbersome.
For some strange reason I couldn't insert more than 7 links in the comment, so here is additional reference regarding comments vs answers: https://answers.sap.com/questions/348530/petition-to-replace-answerscomments-with-reply-or.html
Thanks Jelena, that's a useful set of links. Having started building SAP communities back in 1995, I also know first hand what it's like to see low quality questions, and have realised that nurturing good questions (and generally good behaviour in Q&A) is a continuous process. Part of the reason for this short post was to have the ability to point to something (i.e. a link to this) when commenting on why a question could be improved (i.e. a post like this allows me to explain things better than I can do in a comment).
Regarding comments, answers and structures, I have an observation which may or may not help - Stack Overflow (those who know me know that I'm a big fan of that community and system) has a similar structure, with short flat comments rather than hierarchical ones. And SO seems to do OK.