How To Ask Good Questions

Eric Raymond and Rick Moen’s How To Ask Questions The Smart Way is a fantastic document, and I do refer clueless Bugzilla support-seekers to it fairly often. However, it has the large downside that it’s very long, and written in idiomatic English. A non-native speaker would be overwhelmed.

Hence: How To Ask Good Questions, a much shorter, simpler document inspired by the above. I have attempted to use simple, declarative English and eliminate complex words and constructions while keeping the meaning.

Comments and suggestions welcome – although there’s a fairly high bar for additions, given that we need to keep it simple.

Feel free to point less-than-clueful question askers at this document in support channels you frequent.

16 thoughts on “How To Ask Good Questions

  1. The original document does have translations – but obviously not into every language. And it still takes a very long time to read.

  2. Yeah, I think I like how you boiled it down to the essentials. That might be well enough of a hint for some people, and others who still don’t get it can go on reading the original file.

    Btw: “If you manage to solve the problem, post a follow-up message describing exactly what the problem turned out to be, and how you solved it. You will be grateful for people who post such messages when you are searching for solutions in the future.”
    I would so sign this! How many problems have I solved through this! (Or, on the other hand, how often did I frown when I read “cool, it works now” without any hint to a solution…)

  3. Nice. A few suggestions, just lowering the reading level a bit further:

    – paragraph 2, the credits, belongs in a section at the end of the document – it distracts from the message.

    – I’d rephrase the first paragraph a little after moving that: “This document explains how to ask good questions. You have been sent here because you made a request for help in a discussion forum or newsgroup. However, you asked your question in a way which made it difficult to help you…” (putting purpose to the front, removing ‘unnecessarily’, avoiding repetition of ‘made a request’, remove ‘means it is’ redundancy, and using ‘sent’ rather than ‘pointed at’)
    – remove ‘greatly’ (maybe. the emphasis is good though)

    Section 1:
    – I’d change ‘reception’ into ‘response’.

    Section 2:

    – I’d put item 2 down after item 4, to match the order you’d do things.
    – items 8, 10 remove ‘actually’ (redundant adverb)
    – item 7 remove ‘carefully’ (ditto)

    Section 3:
    – remove ‘exactly’ (redundant adverb)

  4. Excellent article!

    Some comments:

    • I think the verb “to ask” is much simpler than “to make a request”. You could use that in the first few lines.
    • “unnecessarily difficult to help you” -> do you feel the “unnecessarily” bit is very significant? Otherwise, “very” would be shorter and gets the point across as well, I believe.
    • Maybe this is just a display of my ignorance of English grammar, but shouldn’t it be “the FAQ”, if the Q for ‘Questions’ is taken to be plural (as “a … questions” would be incongruent)? It doesn’t make much sense, I think, to tell people to read exactly one Frequently Asked Question :-).
    • “If you don’t understand why something is on this list, do it anyway.” – do we have a better way of coping with such a situation? I can accept that we don’t want people to go “I didn’t understand any of it so I’m asking the stupid way anyway” but I have a bias against telling people to blindly follow rules they can’t back up. But maybe that’s too much for this document – it’s just a thought.
    • “Start a new thread or discussion for your question” – might be worth repeating something like “Search for an existing thread or discussion first” in braces() after this one. I know it’s in the document earlier, but people asking questions the way they shouldn’t tend to excel at skim-reading. Wouldn’t want them to miss that bit.

    A last suggestion about the English used: you could run it through some of the online translator tools and try to read the translation they come up with. This could give you clues about how to simplify the text. You can also safely assume some people *will* use an automated translation tool to read it. Of course, this suggestion assumes that you’re familiar enough with one or more languages other than English to decide how good the translation is, and I’m not sure if you are. I’m sure there will be plenty of willing volunteers to help you out though.

    Taking my own advice, I just looked at the French translation Google Translate comes up with, and it looks pretty good to me, but that may be because I read the English first or because French is a third or fourth language for me – I’m not very good at it, you’re probably better off asking some of the French Mozilla Europe people.
    (I would have checked Dutch, but Google Translate doesn’t do Dutch at all)

  5. Baz, Gijs: Great comments, thanks :-) I’ve taken most of them. The ones I haven’t:

    • Mentioning the doc at the top is important, because the “more” links go to it. I’ve made this more clear.
    • I think the exactly in section 3 is not redundant, because they will have posted approximately what the problem was already
    • I’m not sure we have a better formulation than “do it anyway”; we do link to rationale, after all
    • The point about starting a new thread is a very different one to the point about searching for an existing one. You start a new thread so your message is not buried or mistitled
  6. Wow! A lot of great suggestions.

    One other I would add is to suggest that people answer all questions and at least consider all suggestions. You could explain that sometimes troubleshooting is a multi-step process of eliminating possible causes until the actual cause is found. We often have a problem with users who pick and choose, and often skip over the critical question or the one step that would have solved the problem. And many go away mad if the very first response does not tell them exactly what they should do.

  7. “We have learned the hard way that without such a notice, we will repeatedly be pestered by idiots who think having published this document makes it our job to solve all the world’s technical problems.”

    I stopped reading when I read saw this.

  8. Sorry, to clarify, that came from Eric Raymond and Rick Moen’s document.
    Your’s (Gerv’s) one looks really good to me.

  9. In IE and Opera, the list items under section 2 get smaller and smaller because you’ve forgotten to close the spans.

    Apart from that, I really like the way it’s a short summary article, with links to deeper information.

  10. I also like this short form, and the fact that it links to the original document.

    However, Section 2 item 7 seems to be worded ambiguously.

    It is currently worded “Describe how your problem shows itself clearly and concisely”. This could mean “Clearly and concisely describe your problem and how it shows itself” or it could mean “Make your problem show itself clearly and describe it”.

    As a programmer, I specifically try to do the second thing first. That is how I figure out where the problem is. However, most people are not programmers, and have no idea about programming logic, so once they figure out the problem, they give a description that is little better than “I have a problem, and you had better solve it.”

    As the person who has had to solve problems for others, I have frequently given up on getting a reasonable description, and simply said “show me”. That works when I can go to the user’s computer, but doesn’t do much when the person I am helping is half a world away. This is where it is critical to have a revealing description of the problem.

  11. I think some people pointed at this would take offence at some of the wording in the introduction, and it’d be better to find a form of words that conveys the same sense with less risk of that. In particular this bit:

    However, you either asked in a way which shows you did not do enough research first, or you asked in a way which means it is difficult to help you.

    could be rephrased along the lines of, “We’d like to help you get the best possible answers to your question. Unfortunately, as it’s currently written people may find it awkward to answer your question or be reluctant to do so. Below are some tips on how to ask questions in ways which make it easy for people to help you.”

  12. What does “awkward to answer your question” mean? I think “difficult to help you”, as written, is more accurate.

    Now that I look at it again, #7, “Reading the source code (if you are a programmer)” is WAY beyond what you can expect of the target audience.

    The way it’s worded, this also suggests that you won’t get a polite reply if you can’t find a skilled friend. I would also suggest a more positive tone in that paragraph. I suggest changing

    “You may not get a polite response if you ask a question which could have been answered by doing one of these things.”

    to “You will probably get a more helpful response if it appears that you have made a reasonable effort to solve the problem yourself.”

  13. Oops, the first sentence in my previous message refers to Smylers’ message.

  14. Martijn wrote:

    “‘We have learned the hard way that without such a notice, we will repeatedly be pestered by idiots who think having published this document makes it our job to solve all the world’s technical problems.’

    I stopped reading when I read saw this.”

    (Just to be clear, I’m one of the referenced essay’s co-authors.)

    I certainly respect Martijn’s right to his view, but am not certain he understands what, specifically, Eric’s quoted sentence (above) refers to:

    Since we posted that essay’s first version in 2001, each and every day of the year for the past six years, both Eric and I have gotten, on average, a half-dozen personal e-mails from people who found that essay from one of untold hundreds or thousands of projects that link to it — most of which have prominent disclaimers on their hyperlinks saying “Please don’t send support questions to these guys; they’re not a technical support resource”. Starting around 2003, we started putting prominent warnings near the very top of the essay. The problem persists. Starting around 2004, I replaced the direct mailto: link under my name with one going to a canned e-mail autoresponder I created in Perl that tells them (paraphrasing) “Please feel welcome to write me directly at if you’re writing with comments or suggestions on the essay itself, but NOT for technical support” (etc.). This doesn’t work, either: Several people each and every day, every day of the year, read that autoresponse and then re-mail their attempt at free-of-charge helpdesk mail to me directly, anyway.

    And the crowning irony is that they carry out this abusive, annoying, presumptuous action, trying to get unpaid but skilled consulting work from two guys they don’t even know, in response to an essay those two guys worked very hard and long over to tell people how to interact fruitfully with technical communities — an essay that they plainly are not bothering to read.

    Anyhow: Martijn is offended by Eric having referred to people who do that as “idiots”: I fully respect Martijn’s right to his personal view. However, “idiots” seems, actually, quite mild in context, from my own perspective.

    Rick Moen