don-benjamin.co.uk

I find myself writing this over and over again so I’ve decided to write a post here, so that I can link to it rather than repeating myself.

Any but the most trivial project is going to have some hiccups along the way, particularly during the development/testing process, when these things happen obviously it’s easier for everyone involved if these can be dealt with as quickly and efficiently as possible. The ideal process would be as follows:

1. User finds a problem
2. User reports the problem to the developer
3. Developer sees the problem
4. Developer fixes the problem

The most important point here is that step 4 (fixing the bug) cannot happen before step 3 (seeing the bug), and that step 3 cannot happen unless step 2 (reporting the problem) provides enough information for the developer to see the problem.

If the report doesn’t have enough information, then the problem can’t be fixed, so all that will happen is that the developer will send questions back to the user, which wastes everybody’s time and delays getting the problem fixed.

As much detail as possible is useful in a bug report.  It is important to remember that there will often be multiple ways to do the same job, so something like “I can’t delete a page” doesn’t necessarily tell the developer what link you are clicking on, and this may be relevant.

It also may matter what account you are logged in with, or which records you are working with, so it is important to include usernames and record ids or urls where possible.  It may also be important which web browser you are using (e.g. Internet Explorer 6 or Firefox 3), as some problems will exist on some browsers but not others.

Ideal bug report format

An ideal bug report includes the following information:

1. Exact steps I take
2. What I expect to see
3. What I actually see.

Example report for a web project

For example:

Steps To Reproduce

1. Open Firefox 3.0 Browser
2. Go to http://www.example.com/admin
3. Login with username_x/password_y
4. Click the “Edit Page” button on Page number 15 in the list
5. Edit page form comes up
6. Enter title “Test Page” and content “Test page”
7. Click Save
8. Click “Return to list” to go back to the list of pages

What I would expect to see:

• I would expect to see page number 15 called “Test Page”

What I actually see:

• Page number 15 is called “Wrong Title”

Hopefully this bug report contains all the information the developer needs to reproduce the problem themselves and see it happening.

This is intended as a summary for non-technical users to help in ensuring bugs are reported more effectively, for a more complete investigation I found this much better, more thorough description of how to write a bug report by Simon Tatham author of the excellent PuTTY ssh client.