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?
14 comments
Paulo Z
May 28, 2012 at 12:21 UTC (UTC 0)
Idea:
Register doesntworkdoesntwork (dot) com and point it to this post. So whenever someone gives us a “doesn’t work” answer, to reply with “http doesntworkdoesntwork dot com” and it will redirect the person to this blog post.
milton
May 28, 2012 at 14:21 UTC (UTC 0)
It’s usually helpful trying to walk the problem reporter on the process of solving the bug, so he understands all the requirements listed – quite thorough, by the way – on this post.
Most difficulties on the problem solving process arise from communication shortfalls, and they won’t vanish unless both parts invest on its improvement. It’s much harder when you’re not physically present, but it’s definitely worth trying.
Furthermore, most open projects define instructions for entry-level contributors. A well written guide about the community specific bug-reporting process may diminish the pain, probably filled with links for post like this
Stephen Battey
May 28, 2012 at 17:09 UTC (UTC 0)
Did you stop to consider that perhaps the people who are asking for help by saying “it doesn’t work” are not technically inclined enough to find the information they need. They are coming into irc for guidance, not to be balked at by jerks who can’t get it through their heads that people might not be informed enough to find out what those errors are, or where those logs are.
Don’t be a dick and help them by pointing them to the log files they need to find. If they knew where they were they would have posted them to begin with. If you can’t handle that, gtfo.
Thiago Macieira
May 28, 2012 at 17:37 UTC (UTC 0)
@Stephen: please reread the paragraph of the blog that starts with “I’m not saying I expect a full analysis of the situation by the original poster”. You’re right that the original poster might not have the technical inclination to solve all of the problem by himself and it’s an indication of the fact that said person came to the IRC or a mailing list to ask for help in the first place. But just like the doctor case, the reporter does have some more information to give, since he’s seen an erroneous condition and came to ask because of that.
The whole point of this blog is not that the problem reporter has to do the work by him or herself all the way, but that they already have more information besides “doesn’t work” and they might as well share that information. I also argue that social niceties such as a conversation starter should be waived, in favour of a report of what the situation is, to attract the correct attention of those who can help.
Finally, I did stop to consider that the people who are asking for help are not technically inclined and concluded that they are. In the specific cases I’ve been dealing with, the people who’ve asked for help are software engineers by themselves and they aren’t newcomes to the field.
If you’ve recently been the one to say “doesn’t work”, don’t take this personally. Take this as advice for the next time, so you know where to start looking and how to report your findings, because there will be a next time. And a lot more after that — you’re not expected to know everything
Thiago Macieira
May 28, 2012 at 18:03 UTC (UTC 0)
Let me also say that I’m re-evaluating my position on how to react to IRC “doesn’t work”. If I’m already interested or I have spare time, I will ask “what happened and what did you expect to happen?”, maybe with a snide remark about the crystal ball not working.
But for a mailing list post, which is what prompted me to write about this, you have to provide information.
Jussi
May 28, 2012 at 18:09 UTC (UTC 0)
Hi Thiago!
Hows things? Hope you are well – we haven’t spoken for some time.
Anyway, as a long time helper, I hear you here – it is most frustrating. However, as much as you want to tell people this, I think most of the audience of this blog is probably on the side that already has learnt this lesson.
If you have the issue in the #*ubuntu* channels, the bot has a nice time saver by calling !doesntwork or !elaborate (the second is far better worded than the first).
So, after all this, I think perhaps you may also want to seek alternative venue’s to tell this to people, although I’m sure there is no problem with it being here.
Again though, good post and hope it reaches at least some people who need to know.
Thiago Marcos P. Santos
May 28, 2012 at 19:41 UTC (UTC 0)
Let’s remember that “doesn’t work” is ways prefixed with something, like “my QString doesn’t work”, “my browser doesn’t work”, etc that gives an opening for a reply. IMO this is a good start on the IRC rather them a flood of information that might not make sense.
If someone writes 3 paragraphs of bullshit on the IRC is even worse and honestly, it might be demotivating to help because you know that more is to come.
Johnny
May 28, 2012 at 20:20 UTC (UTC 0)
Stephen is right, Thiago. With Linux becoming more and more popular, for the people who need hand-holding on Windows to open a folder or run a program not on the desktop “It Doesn’t Work” is all they know how to say. They may not know what they expect, but it doesn’t do what they want, and it may not even be the program they wanted.
Windows is popular among the computer unsavy for a reason, and Linux is drawing more and more of the general population in. You may be too young to remember the pre-AOL internet, but when AOL opened the gates, it was like opening the gates of hell. *buntu is doing the same in the OS world, so stand by – It Will Get Worse!
Javier Scappini
May 29, 2012 at 04:01 UTC (UTC 0)
Today I posted on the QtWebkit IRC channel something like “Could someone try this link «link» on a QtWekit environment? It makes my app crash”. Now I’m not sure if this is just enough to get some help, but that was all about the thing, just try to open that Url with Qtwebkit and let me now if it just me or if I found a bug to fill. I thought it wouldn’t help if I said instead “please look at the line 1435 of WebRenderThinggy and tell me why it doesn’t work…”.
Now I suppose I was wrong. Well, no matter… I’ll figure it out anyway, but I’m with the “ice breaking”-like conversation, it really helps me to understan the problem with short-to-long description instead of bunch of info at the same time. Its my point of view.
Thiago Macieira
May 29, 2012 at 08:14 UTC (UTC 0)
@Johnny: I’m sure that you need to help end users to come up with a solution. But even they must realise that “the app I installed doesn’t work” is not enough information. What exactly doesn’t work? Does it launch at all? Does it not do what he expected the application to do? Does it crash, freeze, or show an error message? The point is: something made the user think that something is askew, so why can’t they say that information outright?
In any case, more than once have I pointed out that the cases I’m thinking of are not of a layman, an inexperienced user. I was talking to a software engineer, who was having problems in his own domain. Hopefully, they’re only inexperienced and now know better.
Thiago Macieira
May 29, 2012 at 08:16 UTC (UTC 0)
@Javier: “this link link here makes my app crash” is enough information. Sure, if you could provide a backtrace, a valgrind log, an analysis of the DOM tree that causes the crash or a theory as to which element caused it, it would be extremely helpful. But the proximal cause was that a specific link caused the app to crash. That is all that I’m asking for.
jospoortvliet
May 29, 2012 at 15:14 UTC (UTC 0)
Seen http://xkcd.com/627/ ???
Inge Wallin
May 29, 2012 at 20:03 UTC (UTC 0)
But I *love* to say “it doesn’t work” when I go to one of my colleagues to ask something. That, and “hey, you know about this computer stuff, right?”.
The latter didn’t go so well when I tried it in #kde-devel once, though.
Mike
June 2, 2012 at 00:24 UTC (UTC 0)
Hey Stephan, Did you ever consider that resorting to name calling, e.g., Dick, is excatly the kind of behaviour jerks exhibit? Pot, meet Kettle..
I get where you are coming from, defending the noob, and I have been annoyed by eletists before, but I think it’s a long bow to draw to respond with such a post from a frustrated developer who is getting repeated useless bug reports (which I also deal with every day).
basically, ctfo (hopefully the see still stands for chill.. who knows what the kids these days are doing with our precious acronyms
)