tjout

In my capacity as a "hobby" developer and system administrator for a few small associations I regularly get requests from people if something does not work the way they want. Most of the time this sorts itself out because there was just a small network issue or it turned out to be an user error. But sometimes there is a bug in the system and that needs to be fixed.

The problem here is that the average user does not have the slightest idea what might be relevant or helpful to a developer. Most requests I get stem from the "it does not work" category which is quite useless since I have no way of knowing what it is that does not work. I then have to start an inquiry about what it is and the circumstances in which the problem occurres - a tedious and time consuming task.

The problem is not that people are deliberately ignorant. They just do not know that what they think is a valid request turns out to be useless most of the time for the person trying to fix the problem. In an attempt to not having to repeat myself over and over again about what basic information is needed to fix a problem I created this little guideline.

A good bug report

A good bug report contains as much useful information as possible for the developer to fix the problem by just reading it and following the steps listed. If they do not have to ask any additional questions the report is perfect and the issue will be resolved in no time. The one using a piece of software usually does not know what might be relevant.

Basic rule

Think about the person receiving your report: They do not have any idea about your setup or what you did when you encountered the issue.

This is the basic rule you should follow when submitting a bug report: Would your car technician or your handyman be able to fix your car/house from your description alone without you showing him in person? If not, your description is not good enough. Same goes for software development.

Most developers can not sit next to you and watch the software fail. So you need to substitute this by adding more information even if it seems obvious to you (remember: they do not know your setup).

1. Checklist

The following checklist tries to give a hand when writing a report:

• what OS are you using? (Windows, Mac, Linux, Android, iOS, ...)
• which version? (Win11, iOS 12, ...)
• which version of the software are you using?
• what exactly does not work?
• when does it happen?
• how did you determine that something is not working?
• does it work on another machine? (if you have one)
  • if yes, what is different on your machine?
• ...

2. Description

After following the basic list above you should write out what exactly it is you did when you encountered the problem:

Provide facts

Give as many informations as you can about the circumstances when the problem occurred (I know). Try to reproduce the problem and write down every step.

I opened the app by double clicking. I then clicked on the "Settings" button. When modifying the server address and hitting "Save" the app crashed. The address I entered in the step before was: https://example.com

Skip assumptions

Try to leave out any assumptions about why something happens (I think). This is not to make you feel stupid but you usually do not know how the system works (if you do, this rule does not apply to you). Best case: you are wrong and it gets ignored. Worst case: you tip the developer off into the wrong direction.

I opened the app. When modifying the server address it crashed. This was due to [...]

Final words

Note however that not every one of the points listed above lends itself to every report. If you are not sure whether something is important or not it is better to include it either way. I rather have to filter out irrelevant information than ask (and wait) for a critical piece that halts the whole process.

This post was heavily inspired by the great article written by Simon Tatham.