As somebody who has done a smattering of QA work in the past and as a programmer myself, I see a lot of posts that, while not unreadable by any means could use improvement. With that in mind, I decided I would try to write out a few tips for making bug reports easier to understand, find, and ultimately get fixed presented in a nice simple tl;dnr version followed by a more in depth explanation. This is not intended to replace the SD bug reporting guidelines post which outlines several steps you need to take, but rather a more general style and good practice guide.
This being said, I am far from being a QA expert. My experience was limited to non-critical tool testing for a small linguistics company as part of my miscellaneous things to do as an intern so any suggestions, critiques, additions, copy-edits, etc. are more than welcome. I will try to add more as I notice or think of things. I will attempt to give credit to internet sources used as inspiration or reminders at the end of this post.
- Always check to see if the bug has already been reported first!
- Read all stickies in full.
- One bug per report/topic
- Create descriptive topic names that are descriptive enough to identify the gist and general cause of a bug at first glance.
- Do not post long debug dumps in-line. Use pastebin or attachments instead.
- Include exact, explicit instructions on how to reproduce an error, along with it's frequency whenever it is possible.
- If applicable, give the result that you expected as well as the actual result.
- Be explicit about what are facts, and what are speculations.
- Keep a constructive, helpful tone.
Always Check to see if the bug has already been reported first.
Although it's possible to merge reports in the bug tracker, it's usually a pain and generally won't offer as much clear insight as if the poster had the read previous reports on the bug and only posted new information/confirmations.
Read all stickies in full.
They all contain important information. You should always know the goals and status of the current build. Know the minimum requirements, and make sure you have the latest drivers for your video card.
One bug per topic.
Even if they are very minor and lightly related, one bug per topic/report. If you suspect bugs are linked, it's a good idea to make your speculation known by links to the bugs in question. Having only one bug per topic makes each bug easier to find later, keeps the discussion focused, and is easier to track/assign/mark in the actual tracker.
Create descriptive topic names.
Your bug reports should be titled such that it should be reasonably clear what the bug is, including if possible a general location and very brief description. Whenever possible, you want to aim for a concise but complete sentence (ussually with yourself as the implied subject).
Good: [BUG / CRASH] Game CTD immediately after intro movie
Good: [BUG / GAMEPLAY] Unable to train custom unit with certain equipment.
Good: [BUG / GAMEPLAY] Able to build more farms than should be possible
Bad [BUG / GAMEPLAY] Two farms
Bad: [BUG / GAMEPLAY] Unable to train unit
Bad: [BUG] annoying bug
Bad: [BUG / CRASH] unable to start game!
Don't post entire logs in-line.
Use
pastebin, attachments or other methods of posting debug logs and dxdiag results. Posting the entire huge log in the post is annoying to scroll past when you want to see posts below and can break your post. However, posting just a small section of the log is fine to highlight a speculation. Always link to the full log anyway, even you are absolutely sure that the problem lies within the section you highlighted.
Post exact, explicit instructions on how to reproduce a bug whenever possible.
The goal is for the programmers to be able to easily view the bug themselves. It's nine thousand times easier to fix a bug when I can reproduce it, tinker with it, and use an IDE debugger on a bug than if somebody just told me that there's a bug in some area, even if they intricately described what that error looked like. Make your steps as explicit as possible. Avoid pronouns unless there could be absolutely no possible conclusion.
Consider this: "I started FooApp. It put up a warning window. I tried to close it and it crashed." It isn't clear what the user tried to close. Did they try to close the warning window, or the whole of FooApp? It makes a difference. Instead, you could say "I started FooApp, which put up a warning window. I tried to close the warning window, and FooApp crashed." This is longer and more repetitive, but also clearer and less easy to misunderstand. (Chiark)
It's always better to say too much than too little. Be as specific and complete as possible. Also, include a frequency of reliability when you attempt to reproduce a bug. You should always try to get your reproduction steps to trigger the bug in question every time. However, if it is intermittent (the bane of a programmer's existence) say so.
Give the result that you expected as well as the actual result.
In addition to detailing the bug, explain briefly but explicitly what you expected to happen instead of the bug.
Be explicit about what are facts, and what are speculations.
Even if you are a programmer yourself and you have seen this error a million times, make a very clear distinction between what you know are the facts of the bug and what you think is the root of the problem. "...actual facts ('I was at the computer and this happened') and what are speculations ("I think the problem might be this"). Leave out speculations if you want to, but don't leave out facts." (chiark)
Keep a constructive, helpful tone
edit notes: Trying to get the whitespace to "stick", not having any luck with the rich text editor and my html experience is a little too outdated. I'll make this post more readable at some point if I can.
