Bug report that “doesn’t work”
Report a bug is easy, report a bug that can be easily understood by the programmers to solve your problem quickly is not so easy. Because if we knew it, we wouldn’t let it happen. This short article teaches you how to report a bug that will be quickly acknowledged by programmer so that your issue will be resolved faster.
To make reader understand your problem fully, you need to describe the issue in three perspectives. First is the expectation and second is the surprised outcome. And then you just need to focus on the most important part which is the reproducible steps. List down your steps in instruction set of “1, 2, 3 …”. If a problem only happen to specific OS, then you may start your first step as “In Windows XP, run…” Ensure you test your own steps on newly created project.
To describe a problem in one sentence as a title, you only need to remember two keywords, “should” & “but”. The sentence shall be formed like “…should…, but…” If sentence is too long, you may just spell out your expectation, and describe the ‘but’, i.e. the unexpected behavior at the last step: “Observe that … “. In any case that you have difficulty to describe the expectation, you could at least tell what you like to achieve by saying: “I want to…”
Ambiguous words must be avoided to describe the unexpected behavior. Never say “It doesn’t work”. Firstly we may not always sure what is “it”, secondly very likely we will be guessing what have really gone wrong. A better example is “The red button doesn’t turn to green”. If you are an engineer, you wouldn’t hope to get a call from your customer saying, “after clicking it, nothing happen”.