Asking Questions Well

One of the most frequent issues developers (and support people) have is that questions aren’t asked completely, and both people end up enmeshed in an iterative clarification cycle, unable to resolve the issue until both people understand what’s going on. There’s a decent FAQ on asking questions on StackOverflow, which does tell you to share details and context, but I’m going to go a little further and give you a template for asking questions which should help you get answers quickly.

What does a good problem statement look like?

I did X.

I expected Y to happen.

To my dismay, Z happened instead.

All three pieces are necessary, because frequently the problem is your expectation, not the system you’re trying to use. To clarify, let’s look at an example.

I jumped off a cliff.

I expected to sprout wings and fly across the ravine.

To my dismay, I plunged to my death instead.

Bummer. But the problem wasn’t really about gravity, it was that you expected something to magically happen to counteract it. Frequently users don’t understand how a system works, or what should be expected – this doesn’t make your question bad, by any stretch of the imagination. Part of supporting a product is making sure your users know what to expect, and the documentation may need updating. But the support person isn’t going to be able to help you if they don’t know why you think it’s broken. It may seem obvious to you what should happen, but trust me – more often than not including this piece will get you to your answer faster.

So, let’s go through this piece by piece…

I did X

When you’re explaining what you did, you need to include all the context you can.

• What were you doing, exactly?  Can you reproduce the issue consistently?
• Was it a web issue?  If so, which browser were you using?  Did you try other ones?
• What exact URL or application were you using?  How can someone exactly recreate what you were doing?
• If you’re coding, what language are you using?  Are you using a library?  Include an example of the specific code in question, with pointers to the library and examples you’re following (if applicable)
• If you’re using a web service, what exactly did your request look like?  What were the headers and URL?  If you don’t know how to get those pieces, you need to know – read this article for some pointers.

I expected Y to happen

What did you hope to happen?  Lots of times with an error message or broken request, it’s obvious what you wanted to happen.  It’s still worth your while to include a quick statement.  But if you got a successful response that didn’t match what your expectation was, explain completely and clearly what you were expecting to get, and why.  Point to the documentation supporting your expectation (because it may well need an update or clarification).

To my dismay, Z happened instead

I try to always keep the “To my dismay…” part in there.  It amuses me, it amuses the person answering my question, and it acknowledges the truth of asking a question in this situation – I’m frustrated and sad that I’m stuck because something isn’t working how I want.

But just like with the “I tried X” part, you need to be very specific about what happened.

• Did you get an error in a console or as a result? What did it say, exactly?
• What did you try to get around the issue?
• If you’re using a web service, what were the headers, status code, and/or body returned by the server
• Note that if you are using a library that wraps a web service but asking for help from the API provider themselves, you likely need to dig down and see what the call itself looks like (as the API provider probably doesn’t support the third party libraries)

Following these guidelines will mean it takes a little longer for you to craft your question, but it will save you time, and most importantly, it will save people who might have the answer time. Posting incomplete questions wastes the time and energy of people who might otherwise help you (and they may not come back to see if you’ve added clarification). Showing them that you value their time and energy by completely explaining the issue will increase your chances of getting a complete answer – and if iteration cycles are needed they’ll be much more valuable.