Reporting Bugs
Today I’m not writting about something new. On the contrary, I’m writting about a document that has been available on the net for years. It is, however, so well written and complete that it would be a mistake not to spend at least one post emphasizing its virtues and ignoring its faults. Yes, you’ve guessed it, it’s the essay How to report bugs effectively by Simon Tatham, the author of Putty. I’m talking about it now because some days ago Mr. Tatham accepted my Spanish translation of the document and it is now listed in his website, so it’s a good moment to dedicate some lines to the document, before I forget about it. By the way, I’m aware that the translation has a couple of mistakes that I will correct in order to send him a new version soon.
Not long ago I hadn’t created any open source programs that were available for everyone to use, but in the last years I have created a handful of small tools (I don’t think any of them surpasses 2000 lines of code) that have become a bit popular, especially youtube-dl (which, by the way, is only 405 lines long at the time I’m writting this). youtube-dl has a number of users in the thousands, I think, and the number of emails it generates is much bigger than for any other tool. So far, my *-dl mail folder (dedicated to emails about youtube-dl, metacafe-dl and pornotube-dl) has about 400 messages, and this has given me a good amount of first hand experience in user emails. The style and contents of those emails is quite varied. There are a number of them that simply thank me for creating the program. I try to reply to every one of them and thank them for their support, because it’s very nice. I’ve written a few emails to exclusively congratulate the people responsible for a program, and the emails I received motivate me even more to continue doing so, because now I know how much appreciated those can be.
On the other hand, the most common type of email is the bug report or help request. Of those, some of them are very polite and share the same style I normally use. Let’s call them congratulations-however emails. Let’s see: "First off, thanks for creating blah. It’s a great tool and blah. However, I hit the following bug and blah blah blah." That type of reports is also well received on my side, even when the bug does not really exist or is a user problem or temporary problem that the user identified as a bug.
Some others leave a lot to be desired. Starting by the people who don’t thank you, nor in advance nor after receiving your reply. There are a good amount of these cases. People who write you, for example, about a specific problem they’re having to make your program work. They contact you, they explain the problem as detailed as they can and you take a lot of time to write them a step-by-step guide that even a drunk monkey could follow. Then, silence. Not even a reply thanking you for spending 10 minutes on their problem. Maybe it’s only me, but if I have a problem and someone gives me a long reply trying to explain what the problem is and how to solve it, the first thing I do is to reply thanking them for their time and their efforts to enlighten me, even if that was a complete failure or the instructions weren’t helpful or I didn’t understand a word of what they said. I’d feel bad otherwise.
The worst type of emails are the bug reports that say nothing, do not mention the problem and, on top of that, are so poorly written (by English speakers) that I can barely understand a word of what they say. Or maybe they report about a possible problem with the program and when you request more information they go silent, which leaves you expecting a reply. Maybe you’re even delaying a release in order to fix the possible bug in time, but you have to release it anyway 3 days later because they don’t reply.
So the majority of bug reports and help requests are not as useful and clear as they should be. I think every computer user should spend 10 to 15 minutes reading Simon Tatham’s essay. Really, it looks long but that’s the time it takes to read it. It covers almost every aspect of reporting a software bug or technical computer problem, and those aspects are all explained in detail. It gives all the whys and hows and is very easy to understand. In fact, it’s so complete that parts of it can be extrapolated to other situations like when you’re reporting problems to a system administrator instead of a programmer. To complete it a little bit, given that it explains in detail how to report bugs, I’d mention the why. It’s important to report bugs. Bugs may not only affect you but also other users of the same program. When the program doesn’t have a bug-tracking facility, the number of reports the programmer receives about a bug is a measure of how many people are experiencing the problem and how frequent it is. It lets the programmer concentrate on solving the most important bugs first. It doesn’t matter if you are a clueless user that has problems explaining things. If you lack knowledge and vocabulary, you can replace them with detailed descriptions. It doesn’t matter that you say "I clicked on the Edit word next to File at the top of the program, just below the bar that has the X icon to close it" or "I clicked on Edit on the menubar". So it doesn’t matter that you don’t know what a window, window border or menubar is. If the bug report is detailed enough, anybody can understand what you say, and anyone who reads your report will appreciate your efforts to write it and is more likely to lend a hand to make you and other users happy.
Now, please, go and read the essay. Really. It may even be available in your first language. :)