I can’t sleep because I have some thoughts on the topic.
A bug report is a quality tool, and as such is measurable. The measure of a good bug report is that it gets resolved quickly (or resolved at all). From what I know the best practice is to make it as formal and impersonal as possible. There are couple of traits of a good bug report:
1. A well thought and descriptive title. We should avoid a situation when we will have a number of bugs with a title of “Network problem” or similar. The title should shortly describe the essence of the bug so everyone could easily tell it apart from the others.
2. A short description in the bug body. Again the description should be formal, impersonal and to the point. It should tell what happened in what circumstances. If the bug is simple that should be enough to reproduce it. But put yourself into the reader’s shoes. Will they be able to reproduce it from your description? Or maybe it would be better to go to the next point, which is:
3. A list of steps of reproduction. The best way to tell anybody how to reproduce the bug. Use the numbered list of steps, and at the very end state the wrong outcome, and tell the reader what is expected. If there are more than one unexpected behaviours in the reproduction path you probably found several bugs. Split the bug into different topics.
Remember that before reporting your findings check the list of existing bugs (also the closed ones - in that case reopen it with an appropriate comment). Try to make this effort to spare the time of your coworkers, because filtering out the noise costs time, and time is money.
If you stick to the rules above it will help not only the developers to fix it, but it will help with QA, and deciding whether the bug was really fixed and can be safely closed. Also it will help to create a unit test that will help avoiding the regression.
I think that similar rules apply to user stories, but from their nature (and their name) they are more high level than bug reports. They should also have descriptive title, a short and to the point impersonal summary. Then, where applicable, there should be a list or a table of steps performed by a user, and a list of expected outcome. Vague user stories make everyone unhappy: the customer is unhappy that he doesn’t get what he expected, the programmers are unhappy that they don’t know what to do and must act randomly, and QA is unhappy because they don’t know what is a bug and what is a feature.
I thought that writing this post will make me more sleepy, but it didn’t. Well, I tried. I hope it didn’t make you sleepy when you read it.
