Writing the perfect question

Update: now that I’ve actually posted this, I’ve added a tinyurl to it for easy reference: http://tinyurl.com/stack-hints. Nice and easy to remember for comments :)

A while ago, I wrote a blog entry on how to answer questions helpfully on sites like Stack Overflow. Recently I saw a meta question about bad questions and thought it would be worth following up with another blog post on asking questions. For the sake of convenience – and as Stack Overflow is so popular – I will assume the question is going to be asked on Stack Overflow or a similar Stack Exchange site. Most of the post doesn’t actually depend on that, but if you’re asking elsewhere you may need to tweak the advice a little.

There are plenty of similar resources around, of course – in particular, Eric Raymond’s How to Ask Questions the Smart Way is a perennial favourite. Still, I think I can bring something to the table.

The Golden Rule: Imagine You’re Trying To Answer The Question

If you don’t remember anything else from this post, remember this bit. Everything else follows from here. (And yes, this does smack somewhat of Matthew 7:12.)

Once you’ve finished writing your question, read it through. Imagine you were coming to it fresh, with no context other than what’s on the screen. Does it make sense? Is it clear what’s being asked? Is it easy to read and understand? Are there any obvious areas you’d need to ask about before providing an answer? You can usually do this pretty well however stuck you are on the actual question. Just apply common sense. If there’s anything wrong with the question when you’re reading it, obviously that will be a problem for whoever’s actually trying to answer it. So fix the problems. Improve the question until you can read it and think, “If I only knew the answer to the question, it would be a pleasure to provide that answer.” At that point, post and wait for the answers to come rolling in.

Obviously this is somewhat easier to do if you have a certain amount of experience answering questions, particularly on the forum where you’re about to post. So, what should you be looking out for?

Question title

When a reader first sees your question, they’re likely to be scrolling down a list of snippets. The most eye-catching part of the snippet will be the title – so use that text wisely. While you can include language or platform information, you should only do so naturally – not as a sort of “header”. For example, this is bad:

Java: Why are bytes signed?

But this is okay:

Why are bytes signed in Java?

Of course, you should also include this information in tags, as it will help people who pay particular attention to specific tags.

Ideally, a question title should be a question – but frankly that’s not always feasible. I would recommend favouring a short, descriptive title which captures the theme of the question without actually being a question instead of really trying to crowbar it into the form of a question when it really doesn’t want to be. That’s not an excuse for laziness though – it’s usually possible to come up with a good title which is genuinely a question.

It’s important that the question title is specific though, and has at least some meaning with no other information. A question such as “Why doesn’t this work?” makes absolutely no sense without the rest of the question. Likewise a “question” title of “Please help” is unlikely to do well.

Context

In most cases, anyone answering the question will need to know what language and platform you’re using. The basics should usually be communicated through tags, but it may very well be worth providing more information:

  • Language version (e.g. C# 4)
  • Platform version (e.g. .NET 3.5; note that this isn’t always implicit from the language version, or vice versa)
  • Operating system, if it could be relevant (e.g. particular permissions issues)
  • Any other relevant software (e.g. database type and version, the IDE you’re using, web server you’re connecting to)
  • Any other constraints. This is particularly important. It’s really annoying to give a perfectly good answer to a question, only to be told that you’re not allowed to use feature X or Y which provide the obvious solution.
    • If you have unusual constraints, it’s worth explaining why. Not only does this answer the obvious follow-up comment, but it also gives more information about what other solutions may not be applicable.

Describe what you’ve already tried and the results of any research. (You have searched for a solution to your problem before asking it, haven’t you? Stack Overflow isn’t meant to replace basic search skills.) Often there will be other people in a similar situation, but the answers didn’t quite match your situation. Just like the above point about unusual constraints, it saves time if you can point out differences between your situation and other common ones. It’s even worth referring to other related questions explicitly – particularly if they’re on the same forum. Aside from anything else, this shows a certain amount of “due diligence” – people are generally more willing to help you if can show you’ve already put some effort in.

You should absolutely make sure that you tag the question appropriately. If you’re not sure which exact tags are appropriate, see what gets auto-suggested and look at samples for each one. If that sounds like a lot of work, just remember how much time you may be able to save yourself in the long run. It gets easier over time, of course.

Problem statement

Make sure it’s obvious what you’re trying to get out of the question. Too many “questions” are actually just statements: when I do X, something goes wrong.

Well, what did you expect it to do? What are you trying to accomplish? What have you already tried? What happened in those attempts? Be detailed: in particular, if something didn’t work, don’t just state that: tell us how it failed. If it threw an exception, what was the exception? (Don’t just give the type – give the error message and say which line threw it. If there’s a nested exception, post that too.)

If at all possible, write a sort of “executive summary” at the start of your question, followed by a more detailed description. Remember that on the list of questions, the first few sentences will appear as a snippet. If you can get a sense of the question across in that snippet, you’re more likely to attract views from people who can answer the question.

One trap that many posters fall into is to ask how to achieve some “small” aim, but never say what the larger aim is. Often the smaller aim is either impossible or rarely a good idea – instead, a different approach is needed. Again, if you provide more context when writing your problem statement, we can suggest better designs. It’s fine to specify how you’re currently trying to solve your bigger problem, of course – that’s likely to be necessary detail – but include the bigger goal too.

Sample code and data

I may be biased on this one. I’m a huge believer in sample code, both for questions and answers… and I probably use it in an unconventional way. I usually paste it into a text editor, and try to compile it from the command line. If that’s not likely to work (and the problem isn’t obvious by inspection), I’m unlikely to bother too much with it. Firing up Eclipse or Visual Studio and finding an existing project I don’t care about or starting a new one is going to take much more time.

That means if you want me to look at code, it should:

  • Be standalone. Don’t try to talk to a database unless you really have to. (Obviously for database questions, that’s kinda hard :) If you use sample XML, provide a short but complete XML file for us to reproduce the issue with. (And the same for other file types, obviously.)
  • Be complete. If there are missing imports or using directives, that’s really annoying
  • Actually compile (unless the compilation error is the reason for the question). Don’t give me code which is “something like” the real code but which clearly isn’t the real code, and may well not exhibit the same symptoms by the time I’ve fixed it so that it compiles.
  • Ideally not bring up a UI. Unless your code is about a UI issue, don’t bring one up. Console apps are simpler, and simplicity is a huge benefit when trying to hunt down a problem.
  • Demonstrate the problem. You should be able to say, “I expected the result to be X, it’s actually Y.” (You should actually say that too, so that we can check that we get the same results.)
  • Be as short as possible. If I have to wade through hundreds of lines of code to find the problem, I’m doing work that you should be doing. Often if you work hard to reduce the problem to a short but complete program, you’ll find the issue yourself. You can absolutely do this without knowing what the problem is; you should be looking to the community for their expertise, not their willingness to spend time on your problem doing the work that you can do yourself.

Yes, this is a relatively onerous list. It doesn’t all apply to every problem, but it does apply in a great many situations. While I get put off by reams of irrelevant, badly formatted code, some of which clearly won’t compile, the inverse is true as well: if I can tell by looking at the question that the code can go through a copy/paste/compile/run cycle really quickly, I’m much more likely to pay the question significant attention.

In data-oriented questions, it’s very often helpful to give some sample data. Cut out anything irrelevant (if your real table has 50 columns, you only need to include relevant ones) but make sure that you give enough sample input for it to be meaningful. For example, if you’re trying to group some data by a PersonID column, it’s pretty useless if there’s only one PersonID given, or if each PersonID only appears once. If you are giving examples of expected input and output, make sure it’s clear why that’s the expected output. Often I see questions which give a small number of samples, and there are various ways they could be interpreted. This is one area where it’s particularly important to reread the question from a stranger’s point of view: while a brief summary of the desired results may well make sense to someone who already knows what your app is trying to achieve, it may be gobbledygook to those trying to answer your question.

Spelling, grammar and formatting

I know not everyone speaks English natively. My own command of non-English languages is lamentably poor – I’m incredibly lucky that my native tongue happens to be the lingua franca of the technical world. However, if you’re trying to communicate on an English-language forum, you owe it to yourself to make an effort to write at least reasonably correct English.

  • Please use capital letters where appropriate. It really can make a big difference in the readability of text.
  • Please split your text into paragraphs. Imagine this blog post as one big paragraph – it would be almost impossible to read.
  • Please write actual words. There are undoubtedly some abbreviations which are acceptable to most readers – IMO, IIRC etc –  there’s no reason to switch into text-speak with “gr8″, “bcoz”, “u” and so forth. It’s unlikely that you’re actually writing your question on a phone with only a primitive keyboard; show your readers respect by writing properly. It may take you a few more seconds, but if it means you get an answer quicker, it’s surely worth the extra effort.
  • Most browsers have built-in spelling checkers these days, or at least have plug-ins or extensions available to check your text. Technical text often creates a lot of false positives for checkers, but if your spelling isn’t generally great, it’s worth looking at the suggestions.

Having said all of this, you’re not trying to create a literary masterpiece. You’re trying to communicate your question as effectively as possible. If you’re faced with the choice between an unambiguous but ugly sentence, or a phrase which stirs the soul but leaves the reader confused about exactly what you mean, go for the unambiguous option every time.

One way a huge number of questions can be improved with very little effort is simply formatting them properly. Stack Overflow’s markdown editor is very good – the preview below your input box is almost always accurate in terms of the eventual result, and you can always edit the question later if anything doesn’t quite work. The exact details of the markdown is beyond the scope of this article – Stack Overflow has a detailed guide though – if you’re new to the site, I’d recommend you at least skim through it.

By far the most important kind of formatting is making code look like code. Within a text paragraph, simply surround the code with backticks like this. For blocks of code, just indent everything by four spaces. If you’re cutting and pasting code, it may already be indented (for example if you’re copying code within a class) but if not, the easiest way to indent everything is to paste it, select the whole code block, and then press Ctrl-K or the “{ }” button just above the editor.

One of the important things about code formatting is that it means angle brackets (and some other symbols) are preserved instead of being swallowed by the markdown formatter. In some cases this can mean all the difference between a question which is easy to answer and one which doesn’t make any sense, particularly in terms of generics in Java and C# or templates in C++. For example, like this

Why can’t I convert an expression of type List<string> to List<object>?

makes no sense at all if the type arguments are removed:

Why can’t I convert an expression of type List to List?

Often experienced members of the site will recognise what’s going on and edit your question for you, but obviously it’s better if they don’t have to.

Making a good impression

Leaving aside the main body of the question, there are a few simple ways to get the community “on your side” and therefore more likely to give you a useful answer quickly.

  • Register as a user and give yourself a meaningful name. It doesn’t have to be your real name, but frankly names like “Top Coder” or “Coding Guru” look pretty silly when you’re asking a question which others find simple. That’s still better than leaving yourself as “user154232″ or whatever identifier is assigned to you by default though. Aside from anything else, it shows a certain amount of commitment to the question and/or site: if you’ve bothered to give yourself a name, you’re less likely to be an “ask-and-run” questioner.
  • Keep an eye on your question. There may well be requests for clarification – and of course, answers! If you receive an answer which wasn’t quite what you were looking for, explain carefully (and politely) why it’s not suitable for your purposes. Consider going back and editing your question to make it clearer for subsequent users.
  • Don’t add your own answer unless it really is an answer. Often users add extra details in an “answer” when they should really have just edited their question. Likewise editing your question is generally a better idea than adding a long comment to an existing answer – particularly if that comment contains a block of code (which won’t work well in a comment). If you do change the question in response to an answer though, it’s worth adding a comment to the answer just to let the user know that you’ve updated it though… you may well find they quickly edit their answer to match the revised question.
  • There’s no need to include greetings and sign-offs such as “Hi everyone!” and “Thanks – hope to get an answer soon” in the question. These will often be edited out by other users, as they’re basically a distraction. Greetings at the start of a question are particularly useless as they can take up valuable space in the snippet displayed in the question list.
  • Above all, be polite. Remember that no-one is getting paid to answer your question. Users are giving up their time to help you – so please be appreciative of that. If you’re asking a homework question, explain why you’re asking for help with something that traditionally you’d have to answer all by yourself. If a user suggests that your general approach is wrong and that there’s a better way of doing things, don’t take it personally: they’re trying to help you improve your code. By all means disagree robustly, but don’t start into ad hominem arguments. (This advice applies to answerers as well, of course.)
  • (Somewhat specific to Stack Overflow.) If an answer is particularly helpful or solves your problem, accept it by clicking on the tick mark by it. This gives extra credit to the person who provided that answer, as well as giving more information to future readers.

Conclusion and feedback

Stack Overflow is an amazing resource (along with other Q&A sites, of course). The idea that you can get a good answer to a wide range of questions within minutes is pretty staggering… but there’s an obvious correlation between the quality of a question and the likelihood that you’ll get quick, helpful answers. Put that extra bit of effort in yourself, and it will probably pay for itself very quickly.

I’m hoping to keep this blog post up to date with suggestions received – if I’ve missed out anything, over- or under-emphasized a specific point, or generally gone off track, let me know either in the comments here or mail me (skeet@pobox.com). If this document ends up elsewhere, then that copy may end up being the “canonical” one which is edited over time – in which case I’ll indicate that here.

33 thoughts on “Writing the perfect question”

  1. Great post as always. This’ll definitely be a helpful guide for the “send me teh codez” people. I admit I was one of those for a long time.
    Many people I know use SO with realizing that their questions are being answered by genuine pros, spending their valuable time and effort.
    Personally one the problems I face as a relatively new SO user is that I sometimes find it difficult to decide whether a question should be Community wiki or not, I’m almost always wrong. A little advice on that would be helpful.

    Like

  2. This is a very helpful post. I have to question one assertion though. You say: “You have searched for a solution to your problem before asking it, haven’t you? Stack Overflow isn’t meant to replace basic search skills.”

    I don’t know if I necessarily agree with this. I think the more relevant statement would be, “You have searched for a solution to your problem *on StackOverflow* before asking it, haven’t you?”

    Certainly most questions are already answered out there on some old message board, stuck down on page 3 of a long thread. That doesn’t mean the question shouldn’t be asked again and answered on StackOverflow, where the right answer will appear as the top answer right under the question. Then the next person who has that same question won’t have to do as lengthy of a search.

    Of course, nobody wants a lot of repetition on StackOverflow itself…

    Like

  3. @Scott: I think if I’d already found an answer via a normal search, I wouldn’t post it as a normal question on Stack Overflow. I might post it *with an explicit explanation that I was going to post the answer myself*. Usually I don’t think I’d bother though, unless it had been a really tricky process finding the answer.

    For example, questions such as “what’s the singleton pattern” are easily answered by wikipedia… I don’t think there’s any need for Stack Overflow to have a copy of *every* software-related piece of information in the world. Ditto questions which are easily answered by looking at MSDN or JavaDocs. Of course if people look but don’t find the relevant information even though it’s there, that’s fine… but that’s a different matter.

    Like

  4. I find
    using System;
    using System.Windows.Forms;
    in code samples mostly unnecessary – unless you’re using some less common namespace – and think they have a high noise-to-signal ratio.

    Like

  5. @configurator: I don’t know, it can be annoying to have to compile several times before you’ve “got” all of the necessary using directives. You can fully qualify the names yourself, of course, but I do think there’s value in copy/paste/compile/run with no changes required.

    Like

  6. Maybe I don’t care about them because I’d usually paste the code into my EmptyApplication (which is true to its name and always kept empty), which has the ‘using’s already.

    By the way, I can’t see the captcha images here unless I open them in their own tab (I’m using Chrome), but I don’t suppose you have anything to do with the blog software.

    Like

  7. Sadly, the people most in need of this advice would not only never invest the time it takes to read the article, they would be offended that anyone would suggest that they do. :(

    But, good article anyway. Thanks for writing it (it goes well with your web site articles about code examples, complete and incomplete).

    Like

  8. @Peter: Fixed, thanks. And yes, I’m aware of the “those who need it won’t read it” problem. At least with a memorable tinyurl link it’s easy enough to suggest to people.

    @configurator: I doubt that many people permanently have an extra copy of Eclipse / Visual Studio up just on the off-chance. I still think it’s better to make it complete. It’s usually only a few lines.

    Like

  9. Hi Jon,

    Very interesting article ! However I’m surprised you didn’t say anything about the title of the question : I think picking a good title is very important to attract viewers. There are so many questions with useless titles like “Problem with C#” or “Help me plz”, I usually don’t even bother to read them…

    As for testing the code posted in a question, I usually run it in LINQPad. It’s much quicker than starting a new VS instance and creating a new project, and much more convenient than Notepad + csc.exe: you get syntax highlighting, autocompletion and automatic resolution of missing usings (if you paid for the autocompletion feature of course)

    Like

  10. @Thomas: I’ll update it for the title (and CW) in the next couple of days.

    LINQPad is a solution for C# of course – although I think the command prompt and a text editor (jed in my case) is still faster in some cases :) It’s also easier to use on Linux…

    But the more general point is that for *any* language, if you produce a short but complete program, it’s easy to reproduce the problem. If you leave bits out, the reader is going to have to work out what you’ve left out.

    Like

  11. Nice article, but a bit naive I think. I find laziness is the root of many poor questions. And I don’t think lazy people are motivated to research how to ask better questions. Perhaps the phrase “preaching to the choir” applies?

    Like

  12. @Oorang: I’m not expecting people to find this independently… at least not on the blog. But it’s useful to have somewhere to direct people who’ve asked a question poorly, or perhaps to link to from an obvious place on Stack Overflow itself.

    Like

  13. Nice post. A lot of these tips are also very helpful for end users writing bug reports. Not the technical details of course but the essence of trying to explain to someone else what your problem is.

    Like

  14. Excellent article, Jon.

    I would add, along the lines of omitting greetings and sign-offs, that it’s not necessary or useful to comment on *every* answer with something along the lines of, “Thanks for the answer.” That just clutters the page with useless text. Thanking your answerers are what the up-vote and accept buttons are for.

    Like

  15. Jon, may be it will be helpful if you even post a blog about how to answer questions on Stack Overflow. I have seen that many posters are really snobbish and particularly those who have high reputation.

    Like

  16. Ohh dear. How did I miss that? Usually I tend to skim through the blogs which are very long unless they are tech based. So I might have missed that you have already written a blog on that.

    Like

  17. That last sentence, before the conclusion:

    “I certainly wouldn’t suggest accepting answers just to get your accept rate, even if they didn’t help you.”

    “Even if” makes it sound like not being helpful is an added incentive to accept the answer. Possibly rewrite the sentence, or at least substitute “especially if” in its place.

    A subtlety, for sure, but you said the writeup might get wide distribution, so it’s worth picking nits.

    Like

  18. Great article. One thing that sometimes annoys me on SO is that when people accept the first answer that doesn’t really answer the question. Then when you write a better answer to the question, there’s no way to get to be the accepted answer.

    Like

  19. @Sander Rijken: IIRC you can change an accepted answer to another one. I believe i’ve done that before in the past.

    @skeet: I can’t see the captcha image using chrome either. If I right click it and view it in a new tab it works though

    Like

  20. A small feature request for this very useful article: could you add anchors to the sections so that they can be linked to? A poster whose questions have one kind of flaw will usually suffer others, but sometimes we may want to point them to a specific section. We’d need to use the full URL when linking (tinyurl doesn’t pass fragment IDs through to the target URL), but I, for one, would still find it handy.

    Like

  21. I send people here often because I think you have a very strong position to make these suggestions, and the post here is very well written.

    However, I think historically this page was located at http://tinyurl.com/so-hints (you can verify by looking at a google search). If I use that url, I end up with an error page because it goes to http://msmvps.com/blogs/jon_skeet/archive/2010/08/29/writing-the-perfect-question.aspx . Is there any way to set up some sort of redirect there to prevent broken links?

    Like

    1. Unfortunately I can’t set up redirects – I don’t have any control over msmvps.com. That’s one of the aims of putting everything into jonskeet.uk-based URLs from now on… I’m in control of my own destiny.

      There’s a new tinyurl now though: http://tinyurl.com/stack-hints
      (It’s a shame we can’t update old tinyurl links – I might check out whether there’s some way of fixing that…)

      Like

  22. Nice post, but on the very last bullet point, accept rate hasn’t been shown on Stack Overflow for a while now. I’d actually forgotten all about it until I read that.

    Like

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s