How To Report Technical Issues Efficiently (Template Included)
How to Communicate Technical Issues Clearly and Speed-Up Problem Solving
It is in the interest of small teams, to catch technical issues in applications before they are released to customers.
If you’re in a technical role, you may get frustrated by someone in a commercial role reporting an issue without precision, such as “the device stops connecting over Bluetooth”.
If you’re in a commercial role, you may get frustrated by someone in the technical team responding to your feedback by asking several questions, before taking a look at solutions.
Both frustrations are valid.
They’re valid because different team members have different backgrounds, and in high-urgency scenarios, people default to communicating in language that is native to them.
In today’s article, we’ll take a look at a centralised template, that can be used by:
Any member of a professional team, regardless of their technical background
Anyone looking to report their bugs or issues onto online forums, including students and hobbyists
How Not To Report an Issue
Let’s pretend your team is building a wearable device that connects to a mobile app.
You may notice that while testing the system, the new data you would expect to see updated on the app every few seconds stops appearing.
An easy mistake to make to make, is to guess what caused the observed issue and report your guess to the team.
For our example, someone not involved in building the technology could report the error like this:
The Bluetooth isn’t working
The app looks like it’s crashing
There app is not receiving data
The inefficiency here is that for all we know, the Bluetooth is working fine, the app isn’t crashing and the app could be receiving data - the app may simply be failing to display the data.
For someone involved in building the technology, they may report the issue by going into unnecessarily technical detail.
The inefficiency here is it adds additional layers of complexity to understanding the issue.
How to Report an Issue
Describing what you see, with respect to what you would expect to see will avoid unnecessary layers of dialogue.
If there is one piece of advice to take from this article, it is that.
It will make the process of reacting to issues significantly more efficient, however for best practice, we can add more information to written reports in the following structure:
Title
Brief description of the issue
Environment and platforms used
Expected behaviour
Actual behaviour
How to reproduce
Severity and priority
Title
Do not overthink this - keep it descriptive.
Example: Step Counter not Updating on the App
Brief Description of the Issue
Here you can summarise the issue in your own natural language.
If you were desperate to make an informed guess as to what was causing the issue, it would here.
For example: I was testing the wearable device today, and noticed the number of steps stopped coming through after about 20 seconds or so. The number of steps freezes on what it was on, and does not reset to zero.
Environment and Platform Used
Here is where you would list what technology specifically you were using when experiencing the issue.
If a mobile app is used, it is really useful to say what operating system you’re using (Android, Apple iOS).
On iPhones you can find an “About” section in settings, under “General”, and on Android phones “About Phone” in settings is where you would find this info.
If you are not in the technical team, and wanted engineers to love you, include as much detail here as possible, such as what model of phone you have and even what version of Android/iOS your phone is using.
Finding out that some phones do not support parts of a system you are building, is key information that is vital to catch early - so documenting what devices you were using is more than a formality.
If you are part of a team building hardware, including the version of the device you are using is useful too.
For example:
Phone: Google Pixel 6
Operating System: Android Version 14
Wearable device serial number: 00253
Expected Behaviour
Even if you feel you are mentioning something obvious, describe exactly what you were expecting to observe when using your application.
There may be times where this alone is enough for someone to figure out what went wrong - perhaps there was a miscommunication in what the feature was expected to do.
If it does not immediately provide the cause of the issue, it sets the scene for whoever is reading the report, and provides context when you later describe your issue.
Example: When walking with the wearable device, the app displays the number of steps which is updated in real time. If the device disconnects from the phone, an error message will show.
Actual Behaviour
Describe exactly what you saw, and use your “Expected Behaviour” section as the benchmark for what details to include.
While writing this section, it may be useful to revisit the “Expected Behaviour” section and add new information if needed to put observations here into proper context.
Example: When walking with the wearable device, the app displays the number of steps which is updated up until exactly 20 seconds in. After 20 seconds, the number of steps remains on what it was and does not update. No error message is displayed.
How to Reproduce
What steps could you take to reliably reproduce the issue?
You may not be able to reproduce some issues, however it is helpful to mention what you have done to try.
If you observe the issue happening intermittently, estimating how often you see it happen is still valuable information.
If however you have figured out how to reproduce the issue, you will have done a lot of the work in analysing what causes your issue.
Example:
Connect the device to the phone
Walk for 20 seconds
Observe the number of steps freezing
Severity and Priority
How much of a priority is this issue to deal with? How severe could this be?
Severity and priority is important in the context of how it affects the wider scope of your project or company, but is not needed as a section when reporting to online forums such as Stack Overflow, GitHub or Reddit.
Does this issue block parts of a feature that were planned on being deployed? Or could it block a phase of work that was due to start imminently?
Some systems have fail-safes included, which reduce the severity of a bug taking place, while other bugs can cause systems to crash.
For hardware, some malfunctions cause crashes that are not fixable in the field and as a result would require users to send the devices back to the company.
Example: Severity: 7/10 the app does not crash however step count is an essential requirement for our device. Priority: High, this blocks upcoming trials.
Final Points
Some scenarios will not always require the same structure in issue reports as others.
For example, when I reported an issue with an electronics component not working at all, it was very obvious what the severity of the issue was and my expected and observed behaviour descriptions covered the steps to be reproduced.
I did however decide to go into more detail for what my environment was (I titled it “Tools used”).
Ultimately, when things go wrong on a technical project it is easy to panic and deliver information incoherently.
Applying some basic structure like the above will make the process of problem-solving significantly more efficient.
Template
For easy access, copy and paste the template below into a document that you can keep hold of or share.
Title
Brief description of the issue
Brief summary of the issue in your own words.
Environment and platforms used
Operating system (Mac/Windows, iOS/Android), type of hardware (phone, computer) used, device hardware/software versions.
Expected behaviour
What you expected to observe when you came across the issue.
Actual behaviour
What you actually observed with respect to your expected behaviour.
How to reproduce
What steps do you take to reproduce the issue.
Severity and priority
The impact the issue has on your application or system. The priority of fixing the issue.
Well, most people expect us to be gods who can diagnose their programming issues by reading through the complaint and seeing the logs through the air into their device.