blog.bouah.net/content/posts/how-to-write-a-good-bug-report.md

---
title: "Help me help you"
date: 2018-11-13T03:15:00+00:00
tags: [sysadmin, projects, collabora]
---

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.

[Collabora]: https://collabora.com

[bug-report1]: https://www.chiark.greenend.org.uk/~sgtatham/bugs.html
[bug-report2]: https://wiki.documentfoundation.org/QA/BugReport
[bug-report3]: https://developer.mozilla.org/en-US/docs/Mozilla/QA/Bug_writing_guidelines
[bug-report4]: https://www.quora.com/How-do-I-write-bug-reports
[bug-report5]: https://duckduckgo.com/?q=write+bug+reports

## 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](https://en.wikipedia.org/wiki/Software_bug),
"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](https://support.mozilla.org/en-US/kb/mozillacrashreporter).

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.

[please]: https://secure.phabricator.com/book/phabflavor/article/please_please_please/

### 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_.