7.6 KiB
| title | date | tags | |||
|---|---|---|---|---|---|
| Help me help you | 2018-11-13T03:15:00+00:00 |
|
As some of you may know, I work at Collabora, as a Systems Administrator, and part of my job is to provide support to technical and non-technical "customers" (mostly colleagues, sometimes Collabora's customers).
We have recently been changing our ticketing system, and in the process of doing so, I found myself explaining again how to write tickets, so I thought I might do it here, as it might also be useful to others.
I also regularly contribute to free software projects, and I encounter lots of what I consider bad bugs reports, i.e., incomplete, reporting the wrong things, too many things in the same bag, etc.
There is already a [plethora] bug-report1 [of] bug-report2 [resources] bug-report3 [out] bug-report4 [there] bug-report5 talking about this subject in depth, but I don't think it hurts talking about it more. And also for some reason I can't shake this off my head at 3 in the morning.
This is mostly aimed at non-technical people that I support as part of my job, but it might be helpful for others as well. Comments welcome.
This is also applicable if you want to report bugs to any other projects in the future, and will likely apply to feature requests as well.
This is not a comprehensive list and there are many things you can do to help sysadmins or project maintainers. It's important to find a good balance between what you can do and what the person on the other end will be able to do with the information.
Why bug reports?
Why would you need to write a bug report/file a ticket in the first place?
What first comes to mind is that sysadmins might not know you have issues. And it would probably be beneficial for you, and possibly others, that you tell them.
A ticket is also helpful to be able to track the progress. This will also help other users encountering the same issue and allow them to fix it themselves, or allow you to refer to it in a follow-up ticket, ("You know, that bug I talked to you about six months ago.")
It is also helpful to track the resolution of an issue, ("What happened to my issue?"). Some issues will get fixed and closed, some will not, some might be closed for reasons, without getting fixed.
Why write a good bug report?
You might tell yourself "I don't know anything about computers", and as true as it can be, this is not a requirement to write good bug reports. The error message, if available, or information about your system can easily be obtained and put into the report.
Others might not want to bother, or "don't have time" to write good bug reports. There are a few issue with this if you wish to have your ticket resolved. Questions you don't answer in this first ticket will eventually need to asked some way or another.
Every detail you can give is that much time gained avoiding back and forth for both parties. Some projects will even dismiss your tickets if they think it would take them too much effort to get useful information out of you.
Sysadmins might know about common issues or errors and ways to fix them, but we don't have magical powers (unfortunately?) and we need your help to understand what's happening.
An unhelpful party is only making the process more time consuming for all parties involved.
What is a bug?
This is a trick question.
My helpful friend Wikipedia says, "an error, flaw, failure or fault in a computer program or system that causes it to produce an incorrect or unexpected result, or to behave in unintended ways."
I would try to answer it saying that a bug is everything that a piece of software was designed for, that it is not doing correctly.
This is all vague and subjective, and will sometimes be the cause of project maintainers not accepting your bugs as bugs, but as feature requests, or even discarding them entirely.
How
I have an issue, now what?
Make sure this is only one issue. Do not mix different things together. It makes it easier to isolate and track. People on the other side will be more capable at helping you with precise indications. It happens that you do not know, and in this case they might split the task for you.
Existing tools
Some applications already include automatic bug/crash reporting. For example in Firefox if you type "about:crashes" in the URL bar, you will get a list of all crash reports that have been generated for you and sent to Mozilla servers if you so chose at the time. See more details about this here.
These reports include data useful for developers to find the cause of the crash, and will be stripped out of personal information as possible.
Often it is still good to have a bug report tracking a particular issue. In this case you can link one or multiple related crash reports in it.
Reproducibility
This part is about writing down the steps that lead you to the issue. These are unfortunately not always known, but it is one of the most critical piece of information in the life cycle of a bug request. If sysadmins don't manage to reproduce, they will likely only be able to guess, or unable to help you at all.
The steps can be as simple as:
- Open applicationA
- Click on buttonB
If the issue appear when clicking the button, this is perfect. If the button seems to be the cause but you are not entirely sure, please also say so.
Include any information about your system, what distribution you are using, what software version. Some configuration information also helps.
As sysadmin, what I will be looking after is patterns, to try and identify what part of the system and software is responsible, where the issue lies and if there is code to fix for it, or if it is a configuration or user mistake.
It often feels to me like playing detectives. The more patterns I observe, the more suspects I can cross off my list. It is rewarding to finally solve a complex case, but "boring" ones also help with mental health.
What happens?
Did anything happen at all?
Describe in details what you saw (not) happening. Was there an error message? If so please copy it.
Was there some UI element out of place? Or maybe the issue is hard to explain? You could attach a screenshot.
Application logs are also a gold mine, but they are often hidden to users, thus I do not really expect to see them and will often go get them myself if they exist.
Sometimes it is easier for me to get information directly from the system, to avoid you wasting time with things you do not know or I can do myself.
Why is this a bug / What do you expect instead?
This is also a pretty important step.
What makes you think this is a bug? Can you explain what you were expecting? It might be obvious to some but not to others.
When reporting to a project, if there is no obvious solution for your issue, maybe you can propose a few ideas to guide developers.
I have submitted the report
Thanks a lot! I really appreciate it.
But wait! Don't leave! The adventure has only just started.
If you managed to read until here, great! If there is one thing to remember from this article I would want it to be the following: Please help me help you.