Every now and again, someone posts on IRC or to a mailing lists about an issue they’ve had and their description of the problem is that “it doesn’t work”. There’s nothing more annoying to the person giving help than to see that description…
That happened to me twice again today, which is what prompted me to write this blog. At this point, I’d like to shamelessly plug in here my work on Lydia Pintscher’s Open Advice book: I wrote chapter 10 in that book, called “The Art of Problem Solving“. And if you haven’t read the book yet, or even skimmed through it, I recommend you do it. It’s full of great advice from experienced people, in many areas related to open source development, contribution, advocacy, or other forms of participation.
The first section of my chapter is called Phrasing the question correctly, where I wrote:
The most useless problem statement that one can face is “it doesn’t work”, yet we seem to get it far too often. It is a true statement, as evidently something is off. Nevertheless, the phrasing does not provide any clue as to where to start looking for answers.
The question is where we start off. In the context of asking for assistance on IRC, mailing list, or forum, it’s supposed to give the help-giver hints as to what is askew, so that they can begin forming theories as to the root causes of the problem and applying problem-solving techniques to confirm or deny it. But note how all the techniques rest on knowing what exactly is wrong.
I’m not saying I expect a full analysis of the situation by the original poster, just as I don’t expect a person who is not a health professional to do the same when going to the doctor’s. But a minimum of information is necessary. Imagine you were to go to the doctor and tell him or her that “I’m feeling ill”. What do you think the doctor will do with that information? So why do people think that “it doesn’t work” is enough information for an engineering help-giver?
At this point, you might say that “it’s just a conversation starter,” a way to break the ice and begin the discussion. And while I might be inclined to agree with you in a social context, in a live face-to-face discussion, I do not when it comes to interaction via the Internet. It’s definitely the case when the communication is not in real-time: if it takes six hours for an answer to come, then the first usable theory won’t reach the poster until 12 hours after the first post.
But even in real-time communications it’s necessary, as more often than not, it’s a matter of attracting attention of the help-givers. If I’m somewhat busy, you cannot expect me to spend precious minutes asking, “so, what exactly happened? what did you expect to happen?”
How would you know what to say in the original post, then? Here are a couple of suggestions, some of which are, I hope, obvious:
- the description of what actually happened;
- the description of what was supposed to happen;
- the actions that you took that led up to the event;
- a description of the environment, such as versions of the relevant programs and settings you changed;
- the logs of any programs involved that might include relevant information;
- if you’ve tested other conditions and whether they’ve failed or succeeded;
- if it’s a recent issue, when it started happening and when the last time you noticed it not to happen was;
- any theories you might have about the issue;
- what you have already done, so far, to fix the issue;
- what sources of information you’ve used to diagnose the problem.
Try to provide as much information as possible, in a concise manner, appropriate to the medium. For example, on IRC, you cannot write a 20-line description of all the theories you may have, but it’s certainly doable to describe the event that led you to think, “hang on, this isn’t right,” and provide a link to further information such as a pastebin of the logs.
Some other quick advice:
- Use your brain! Exercise it, that’s how it develop. Read the logs that you’ve got, especially compiler error logs, and interpret them. Form your own theories and test them if you can, disproving some and proving others.
- Don’t argue with the evidence. If the compiler tells you there’s an error, then you’ve got an error (the exception is when you suspect a compiler bug);
- Do your homework: use Google and other search tools to find out more information. For example, if you’ve got an error message, search for that specific message. If you don’t do this, you may get the answer in the form of a LMGTFY link.
- Use the appropriate channels: asking the wrong audience will not get you closer to the answer, but might raise your frustration, that of your audience and may delay the process.
- Know your tools, know how to use them. It might be acceptable for a newbie, student or hobbyist not to know them, but it’s not for a professional. Not only should you know how to use them, but also a little of how they work.
- The first error is usually the most important one.
- A warning is (often) not an error, but warnings weren’t meant to be ignored.
I’m sure there are more advice that my readers can give. What else would you suggest as advice or as information a help-giver could use?