Remove dos lineendings (wth?)
Signed-off-by: Maxime “pep” Buquet <pep@bouah.net>
This commit is contained in:
parent
358f9770eb
commit
63ad6b86fa
GPG key ID:
DEDA74AEECA9D0F2
1 changed files with 189 additions and 189 deletions
|
|
@ -1,189 +1,189 @@
|
|||
---
|
||||
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 as well as non-technical
|
||||
"customers" (mostly colleagues, but also 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 might help
|
||||
future you encountering the same issue again be able to fix it yourself, or to
|
||||
refer to it later on.
|
||||
|
||||
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.
|
||||
|
||||
Forgetting about the job for a second, in the context of a free software
|
||||
project for example, where people often volonteer, they might just not bother
|
||||
answering you in return if you don't do any effort.
|
||||
|
||||
For my use-case, as I am paid to provide support, the issue is that 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.
|
||||
|
||||
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 the issue.
|
||||
|
||||
An unhelpful party is only making the process more painful for all parties
|
||||
involved.
|
||||
|
||||
## What is a bug?
|
||||
|
||||
This is a trick question.
|
||||
|
||||
My helpful friend [Wikpedia 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_.
|
||||
---
|
||||
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 as well as non-technical
|
||||
"customers" (mostly colleagues, but also 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 might help
|
||||
future you encountering the same issue again be able to fix it yourself, or to
|
||||
refer to it later on.
|
||||
|
||||
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.
|
||||
|
||||
Forgetting about the job for a second, in the context of a free software
|
||||
project for example, where people often volonteer, they might just not bother
|
||||
answering you in return if you don't do any effort.
|
||||
|
||||
For my use-case, as I am paid to provide support, the issue is that 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.
|
||||
|
||||
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 the issue.
|
||||
|
||||
An unhelpful party is only making the process more painful for all parties
|
||||
involved.
|
||||
|
||||
## What is a bug?
|
||||
|
||||
This is a trick question.
|
||||
|
||||
My helpful friend [Wikpedia 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_.
|
||||
|
|
|
|||
Loading…
Reference in a new issue