Remove 'Existing tools' section, move content down to Reproducibility

Signed-off-by: Maxime “pep” Buquet <pep@bouah.net>

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

@@ -0,0 +1,171 @@
+---
+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. This is mostly
+aimed at non-technical people that I support as part of my job, but 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 _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 progress of a task.  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 conversation, ("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?
+
+Try to ensure 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 guide you and/or split the task for you.
+
+### 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 only be able to guess, or most likely unable to help
+you at all.
+
+The steps can be as simple as:
+
+- Open applicationA
+- Go to tabB
+- Click on buttonC
+
+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.
+
+You can usually get all this information in the help menus of applications.
+
+![][gnome-version].
+
+Some applications already include automatic bug/crash reporting.  For example
+in [Firefox][crash-report] 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.  These reports include data
+useful for developers to find the cause of the crash.
+
+
+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.
+
+[crash-report]: https://support.mozilla.org/en-US/kb/mozillacrashreporter
+
+### 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.
+
+[please]: https://secure.phabricator.com/book/phabflavor/article/please_please_please/
+
+### Why is this a bug?
+
+What makes you think this is a bug?  What did you expect the application to do
+instead?  It might be obvious to some but not to others.
+
+When reporting to a project, if there is no obvious solution for your issue,
+you may want to 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_.