So you asked a question on a mailing list...

[cdybedahl]

Intro

I read a number of technical mailing lists (and similar other fora). On them, people ask a lot of questions. A whole lot of those questions suck, and for that reason go unanswered. This posting is meant to be a simple guide to how to write a question that is possible to answer. The hope is that it'll reduce the number of badly asked questions by at least a handful or so.

"Is there something that does what Flabbergastle does?"

I don't know. I've never heard of Flabbergastle. I haven't got a clue what it does. It's possible that I know of something that does exactly what Flabbergastle does, only much better and with dancing sexy people and free chocolate. But unless you tell me what Flabbergastle does, I will never know that it's what you want, and so I'll never tell you. And so you don't get the sexy dancing people and the chocolate.

"It doesn't work!"

You'll probably get a shitload of replies to this one, actually. All of them will be useless to you, and only serve to annoy the rest of the readers. This is because you didn't tell us anything whatsoever except that something did not conform to your expectations, but you said it in such a way that lots of people will think they understood what you meant. So they'll reply according to that. Unless they really are mindreaders, they'll be wrong, and both you and they will end up frustrated. In the real world, mindreaders are exceedingly rare, so please ask your question in a better way. That means including these things in the post:

1. What you are trying to achieve.
2. What you did.
3. What you expected to happen.
4. What happened instead.

Point three is in bold because even people who do think to include the other three points miss that one, and quite often the problem lies with their expectations.

"What's wrong with this?"

...followed by the entire source code to an application. All umpteen thousand lines of it.

This is mostly done by people who have figured out that posting "It doesn't work!" isn't enough to solve their problem, and who try to provide enough information for others to help them. Not seldom they react badly when their effort is not met with appreciation.

This ties in closely with the points above, since in theory it answers point two in the list. The problem is thus two-fold: it doesn't answer points 1, 3 and 4, and the answer to point 2 is utterly undigestable. We have jobs. We don't have the time to read your entire application and figure out its problems (at least unless you pay us to). You really have to prune your code down to an example short enough to read but long enough to demonstrate the problem. Really. You have to.

Not seldom, you'll find that in the process of doing this pruning you'll accidentally discover the source of your problem. When this happens, you are morally obliged to post a prayer of thanks to the Great Tech Support Teddy Bear.

"I get this error message, what does it mean and how do I fix it?"

...with no information whatsoever except the error message. Which is almost invariably of one of two kinds. One is where the message very clearly spells out exactly what's wrong and how to fix it, which makes you wonder if the poster even tried to read it. This not seldom leads down a conversational road that ends with a strong temptation to urge the poster to get someone smarter to do the programming. The other kind is the one where the error message is so hopelessly generic that it's completely impossible to even guess what the poster was doing. Which is, basically, just a special case of "It doesn't work!".

Sometimes it is possible to tell from the error message exactly what the poster did wrong. This is almost never flattering for the poster, since it usually is something along the lines of trying to run their Ruby script with bash, or running their C++ program without compiling it first.

Comments

[waveney.livejournal.com]

What you are trying to achieve.
What you did.
What you expected to happen.
What happened instead.

Years ago when I was at the front of the fault idenitifaction team on a large project I got so fed up with stupid reports I rewrote the form that all incidents have to come with, it had four very familier headings:

What was the state of the system before you did anything

What you did (don't just quote a test number, tell me what you actually did)

What happened

What did you expect to happen.

As amazing as the range of stupid things reported to me was, what was also alarming is what they did not. Anytime I ran out of incidents to analyse, I just went to the machine room and picked up the discarded machine logs - and invariably found further real incidents that they had not reported - such as trying a test three times before it worked - why had they not reported it had failed twice?