Introduction

Effective issue reports are the ones most likely to be solved. These guidelines explain how to write such reports.

Preliminaries

  1. Make sure your software is up to date.
  2. Search the change log to see if your issue has already been resolved.

Environment Information

This is extremely important. Firstly, the developer will need to know which exact version/build of software you had an issue with. This information can be found by selecting Help » About. Secondly, they will need information regarding your environment such as:

  • Operating system version, build and service pack
  • Platform x86 / x64
  • Amount of memory and free memory
  • Amount of free space on system drive
  • Version of .NET framework installed
  • Time zone, culture and encoding


Example Environment Information
Application: Blade® Professional v1.11 (Build 1.11.15027.00) 
Operating System: Microsoft Windows 7 Ultimate x64 (Microsoft Windows NT 6.1.7601 Service Pack 1 (Build 6.1.7601.65536))
Platform: x64
Memory: 32GB
System Drive: 3TB / 2.15TB Free
.NET Framework: v4.0.30319.34209
Time Zone: (UTC) Dublin, Edinburgh, Lisbon, London (GMT Standard Time)
Culture: en-US
Encoding: Western European (Windows)(ID: 1252)

Writing Precise Steps to Reproduce

How can a developer reproduce the issue on his or her own computer? Steps to reproduce are the most important part of any report. If a developer is able to reproduce the issue then it is very likely to be fixed. If the steps are unclear, it might not even be possible to know whether there is an issue or whether the issue has already been fixed.

Describe your method of interacting with the application in addition to the intent of each step.

  • Imprecise: "Open the history file".
  • Precise: "From the File menu select Import » Data from Folder and select the Roaming\Mozilla\Firefox folder".

 

After your steps, precisely describe the observed result and the expected result. Clearly separate facts (observations) from speculations.

  • Imprecise: "It doesn't work"

  • Precise: "The application searched through each folder for a supported file type and logged each found file to the log window. Once all the supported types were found, the application started to import data. When it reached the places.sqlite file, it logged a system.io exception showing access denied."

 

If the issue seems egregious, there might be something unusual about your system setup that is a necessary part of the steps to reproduce the issue. See if you can reproduce the issue on another system. If the issue only happens on your system, try to figure out what is unusual about your system compared to the other system.

If you can reproduce the issue, then think about using screen capture software to create a video. This will allow the developer to see exactly how the issue is reproduced.

Source Data

The source data can have an impact on diagnosing an issue. It may be that your data has some corruption or is in a format that has not previously been seen. It could be that the specific version of your data has not been supported by the version of software you are using. The quickest way to resolve issue that are data related is to let the developer have access to the original data. Consider using a file sharing platform such as Copy by Barracuda.

Log Files

Please remember to include any log files. Our logging and error logging files have information which will help us get to the root of the problem. It is very important that the complete files are sent to us.