Update documentation

docs/environment.rst

@@ -0,0 +1,42 @@
+Environment
+===========
+
+Your settings, your locale, the set of applications you've installed and everything that might make things on your computer unique, or somewhat different than on somebody else's is called your **environment**.
+
+If the issue is always reproducible on your computer but the very same steps do not trigger it on other computers, then the environment is key and the differences between the environment of the two computers should be reviewed.
+
+.. important::
+	When other people can't reproduce your issue with the steps you provided, give them more information about your environment.
+
+Depending on the nature of the issue, you might look at different parts of the environment.
+
+Locale
+------
+
+Your locale consists in your language and regional settings.
+
+Here are a few common issues related to locales:
+
+* Crashes due to a bad translation
+* Missing translations
+* Crashes due to unicode characters
+* Wide widgets or applications due to long translations
+* Failure to show special characters
+
+When an issue is specific to your locale, set your language to English, log out and log back in and see if the issue is still happening.
+
+To see or share details about your locale, open a terminal and type ``locale``.
+
+List of packages
+----------------
+
+An issue might happen because of a missing package or a missing library.
+
+You can use the terminal to search. For instance, to search for the foobar library, type ``apt search foobar``.
+
+To see or share the list of installed packages on your system, type ``dpkg -l``.
+
+You can also check the version of a particular package. To check the installed and available versions of cinnamon for instance, you can type ``apt policy cinnamon``.
+
+Last but not least, you can list your repositories with ``inxi -r``.
+

docs/errors.rst

@@ -0,0 +1,36 @@
+Errors
+======
+
+In many cases your computer detects the issue and reports an error message.
+
+Always read error messages and try to understand them. They often explain the cause of the issue and sometimes even suggest workarounds or solutions for it.
+
+System logs
+-----------
+
+System logs often contain clues for crashes, hardware, driver and networking issues.
+
+You can use the following to go through system logs:
+
+* The System Logs tool (from the application menu)
+* The ``dmesg`` command
+* The ``journalctl`` command
+* The ``/var/log/syslog`` file
+
+Session Errors
+--------------
+
+If you can't log in or if the issue is related to your desktop environment, check the ``~/.xsession-errors`` file, and log files from the ``/var/log/lightdm/`` directory.
+
+Application output
+------------------
+
+If an application isn't working correctly, close it and run it from the terminal. It might output error messages in the terminal which will give you clues about the cause of the issue.
+
+Crashes
+-------
+
+After a crash, you can launch :menuselection:`Menu --> System Reports` to see information about the crash and get a stack trace for it. This information is valuable for developers and helps tremendously when trying to understand causes of a crash.
+
+.. important::
+	When reporting bugs, always look for errors and always report them.

docs/faq.rst

@@ -0,0 +1,17 @@
+Can ideas or feature requests be submitted?
+===========================================
+
+Yes, absolutely. Github issues aren't necessarily bug reports. They can also be ideas or feature requests.
+
+When submitting an idea or a feature request, try to indicate it in the issue title, so that it's immediately clear to developers they're not looking at a bug report.
+
+Why are ideas and feature requests closed?
+==========================================
+
+In the past, issues for "good" ideas (this is highly subjective) used to remain open until the idea was implemented, while "bad" ideas (or at least ideas which weren't deemed urgent, feasible or important enough) were closed.
+
+This was a mistake, because it focused on legitimacy and perception and it tried to give issue authors something we could not afford: traceability and reporting of their ideas' implementation.
+
+The process is much simpler now and much more efficient. When you submit an idea, it is processed and then closed. It might lead to an implementation, it might lead to a design discussion within the team, it might be planned for a particular release and put on the roadmap, it might lead to nothing at all or stick in people's mind as something they could improve later on. Either way, your role is done when the idea is reported and once it's understood by the development team.
+
+When the process of gathering information about your idea and understanding it is finished, your issue can be closed. The eventual and possible implementation of that idea is separate and shouldn't keep the issue open.

docs/how.rst

@@ -0,0 +1,43 @@
+How
+===
+
+Provide precise and relevant information
+----------------------------------------
+
+The first thing developers try to do is understand how to reproduce the issue.
+
+Always give them the relevant information:
+
+* Steps you perform to always reproduce the issue on your computer (be as precise as possible)
+* Particularities in your environment which might be relevant or different than the developers environement (your locale, your drivers, etc..)
+* Any relevant error message of software output
+* Screenshots which show the issue
+* Anything that might make it easier for developers to understand and/or reproduce the issue
+
+Provide stack traces for crashes
+--------------------------------
+
+When reporting a crash, provide the following:
+
+* The ``dmesg`` line for the crash.
+* A stack trace for the crash (you can get one using :menuselection:`Menu --> System Reports`)
+* As for other bugs, steps to reproduce the issue.
+
+Explain your expectation
+------------------------
+
+It might sound silly, but sometimes a bug report is clear on what the software does but not on what the author expects it to do. This can lead to a misunderstanding.
+
+If possible, briefly explain why you think the software behaviour is wrong and what you would expect it to do instead.
+
+Be patient and pleasant
+-----------------------
+
+Most people are. It's easy to be grumpy (or sometimes just to "sound" grumpy) on the Internet. Developers and users alike should do their best to make the interaction as pleasant as possible.
+
+This is open-source after all, we're all in it for the fun (even though, let's face it.. bugs aren't exactly the funniest aspect of it).
+
+Feel like a hero
+----------------
+
+When people see their reports closed or no answers to their comments they might assume they wasted their time. That assumption is completely wrong. There are very few developers and many many users. It is not possible to interact with everybody and to fix bug some reports without closing many. Linux Mint is getting better and better though, every day, thanks to people like us, and people like you. It is fueled by effort and feedback. If you read until here and you contributed feedback or bug reports, you should feel like a hero. It takes time to pat each others on the back and we surely don't do it enough.

docs/index.rst

@@ -16,25 +16,23 @@ This guide will help you troubleshoot issues on your computers, find help within
    reproducibility
    responsibility
    change
-   analysis
-
-   Research and Help
-   Solutions and workarounds
-   Reports
+   errors
+   environment
 
 .. toctree::
    :maxdepth: 1
    :caption: Reporting bugs
 
-   Goal (to fix bugs, not to document everything that is or might be wrong)
-   Invalid bug reports (what not to report)
-   what info to include (enough for devs to reproduce or understand)
-   where (which project, upstream)
-   the lifecycle of a bug report
+   why
+   when
+   what
+   where
+   how
 
 .. toctree::
    :maxdepth: 1
    :caption: Frequently Asked Questions
 
-   Ideas and feature requests
+   faq
+
 

docs/sections.rst

@@ -4,7 +4,6 @@
 
 General concepts
 
-Finding help
-
 Reporting bugs
 
+Frequently Asked Questions

docs/what.rst

@@ -0,0 +1,9 @@
+What
+====
+
+It's hard to generalize and there will always be special cases.
+
+Ideally **what** you should report are actual bugs, i.e. issues which are deterministic, understood, analyzed and thus fixable.
+
+.. note::
+	Do not report observations, they are rarely useful to developers, and when they are they usually require a large amount of time and efforts to be turned into improvements.

docs/when.rst

@@ -0,0 +1,13 @@
+When
+====
+
+Do not open bug reports before troubleshooting is finished. A particular project might have 2 developers, 100 open bug reports, 1,000 active users on the forums and IRC and a million users overal. You should troubleshoot the issue on your own first, and as much as you can, and then rely on other users in the community for help, before interacting with the development team.
+
+You should report a bug when all these conditions are met:
+
+* You're absolutely sure it's a bug (you've established reproducibility, responsibility and identified the cause)
+* You've gathered enough information for the team to work on and you're confident it will quickly lead to a fix (error messages, steps to reproduce etc..)
+* The issue wasn't already reported
+
+.. important::
+	Although developers can help with questions, troubleshooting and analysis, there are very few of them and many other bug reports open. Use them for what they're best at: Fixing things. Only open bug reports when everything is done already (observation, troubleshooting, analysis, gathering of information, understanding of the cause) and the only thing missing is the actual fix. Don't rely on developers to do the analysis/troubleshooting for you. A bug you don't understand is unlikely to be a bug they'll fix overnight.

docs/where.rst

@@ -0,0 +1,105 @@
+Where
+=====
+
+The Linux Mint operating system is made of thousands of software components. Once you've identified the component responsible for your issue, you need to identify who's maintaining it.
+
+Mint and upstream components
+----------------------------
+
+There are two types of components within Linux Mint:
+
+* Mint components are maintained or patched by Linux Mint
+* Upstream components are maintained by Ubuntu (or Debian in the case of LMDE)
+
+You can use the terminal to get information about a particular component.
+
+Use ``apt contains`` to find the name of the package containing a particular file.
+
+For instance, if you are chasing an issue in the file ``/usr/share/polkit-1/actions/org.gnome.gnome-system-monitor.policy``, you can type:
+
+.. code-block:: console
+
+	apt contains /usr/share/polkit-1/actions/org.gnome.gnome-system-monitor.policy
+
+	gnome-system-monitor: /usr/share/polkit-1/actions/org.gnome.gnome-system-monitor.policy
+
+The output tells you this file is part of the ``gnome-system-monitor`` package.
+
+Once you know the name of the package, you can use ``apt policy`` to see who's maintaining it:
+
+.. code-block:: console
+
+	apt policy gnome-system-monitor
+
+	gnome-system-monitor:
+  	Installed: 3.18.2-1ubuntu1
+  	Candidate: 3.18.2-1ubuntu1
+  	Version table:
+ 	*** 3.18.2-1ubuntu1 500
+        500 http://archive.ubuntu.com/ubuntu xenial-updates/main amd64 Packages
+        100 /var/lib/dpkg/status
+        3.18.2-1 500
+        500 http://archive.ubuntu.com/ubuntu xenial/main amd64 Packages
+
+
+As you can see above, gnome-system-monitor comes from the Ubuntu repositories and is therefore an upstream component. Bugs related to it should be reported to Ubuntu.
+
+Here's another example:
+
+.. code-block:: console
+
+	apt policy gnome-calculator
+
+	gnome-calculator:
+  	Installed: 1:3.18.3-0ubuntu1.16.04.1.mint1
+  	Candidate: 1:3.18.3-0ubuntu1.16.04.1.mint1
+  	Version table:
+ 	*** 1:3.18.3-0ubuntu1.16.04.1.mint1 700
+        700 http://packages.linuxmint.com sylvia/upstream amd64 Packages
+        100 /var/lib/dpkg/status
+        1:3.18.3-0ubuntu1.16.04.1 500
+        500 http://archive.ubuntu.com/ubuntu xenial-updates/main amd64 Packages
+        1:3.18.3-0ubuntu1 500
+        500 http://archive.ubuntu.com/ubuntu xenial/main amd64 Packages
+
+This time we're looking at gnome-calculator. As you can see above, Linux Mint provides version 1:3.18.3-0ubuntu1.16.04.1.mint1, and that's the version which is installed. In this example, our version of gnome-calculator is therefore a Mint component and bugs related to it should be reported to Linux Mint.
+
+Upstream bugs: Launchpad and Debbugs
+------------------------------------
+
+If the bug relates to an Ubuntu component, it should be reported on `Launchpad <https://bugs.launchpad.net/>`_.
+
+If the bug relates to a Debian component, it should be reported on `Debian's bug tracking system <https://www.debian.org/Bugs/>`_.
+
+.. important::
+	Before reporting upstream bugs to Ubuntu and/or Debian, you should always make sure the issue can be reproduced in Ubuntu and/or Debian. Install Ubuntu (or Debian) in a virtual machine and try to reproduce the issue. If the issue is specific to Linux Mint, it should be reported to Linux Mint directly (whether the component is upstream or not).
+
+The base used by LMDE 3 is Debian 9 'Stretch'.
+The base used by Linux Mint 18 is Ubuntu 16.04 'Xenial'.
+The base used by Linux Mint 19 is Ubuntu 18.04 'Bionic'.
+
+MATE bugs: Github/mate-desktop
+------------------------------
+
+MATE is co-developed by Linux Mint.
+
+Bugs which affect MATE or one of its components should be reported on the `MATE Github organization <https://github.com/mate-desktop>`_.
+
+One exception to this are bugs which are specific to Linux Mint. For instance, if a bug relates to mintmenu, mintdesktop or a mint theme in MATE, please report it to Linux Mint directly.
+
+Cinnamon, Xapps and Linux Mint bugs
+-----------------------------------
+
+Linux Mint has three development teams:
+
+* The Cinnamon development team maintains all Cinnamon components, including nemo and muffin.
+* The XApp development teams maintains all cross-distribution projects such as the Xapp applications (pix, xed, xreader, xplayer, xviewer), libraries but also slick-greeter, blueberry..etc.
+* The Linux Mint development team maintains all the Mint tools and other components distributed via the Mint repositories.
+
+When reporting a bug to one of these teams, try to find the compoment on the `Linux Mint Github organization <http://github.com/linuxmint>`_.
+
+For instance, a nemo bug should be reported on `Nemo <http://github.com/linuxmint/nemo>`_, a mintmenu bug should be reported on `Mintmenu <http://github.com/linuxmint/mintmenu>`_, an xplayer bug on `Xplayer <http://github.com/linuxmint/xplayer>`_ ..etc.
+
+If you want to report a general issue about Cinnamon, you can use `Cinnamon <http://github.com/linuxmint/Cinnamon>`_.
+
+If you want to report a general issue about Linux Mint, or an issue about an upstream component which is patched by Linux Mint, or an issue about an upstream component which is specific to Linux Mint, you can use `Linux Mint <http://github.com/linuxmint/linuxmint>`_.

docs/why.rst

@@ -0,0 +1,15 @@
+Why
+===
+
+The reason why bugs are reported might sound obvious, but it's very important to properly understand it.
+
+Bug reports are only valuable when they lead to a bug fix or an improvement. Only a small portion of open bug reports do. For software to improve quickly, development teams need to identify and work on bug reports which have the best chances of leading to a fix.
+
+Ideally, the development team should be aware of all open bug reports and work on the ones which have the greatest chances of improving the quality of the software. In open-source though, where teams are small and communities are huge, the number of open bug reports is usually very big and teams cannot read, process or be aware of all open bug reports. This is ok on small projects where there are 10 reports or so, but certainly not on large ones with thousands of open bug reports.
+
+The author of a bug report suffers the issue and considers it to be real, whether or not the development team is able to reproduce it and no matter what it thinks of it. When the bug report is closed, the author might find it hard to accept. There can be feelings of frustration, legitimacy, ingratitude and ignorance at play. It's really important to set aside any personal feelings when it gets to that and to focus on being efficient.
+
+When you report a bug, both you and the development team are focused on one thing and one thing only: Improving the software. Developers already know you enjoy their work, and you already know they value your feedback. The only question isn't whether your issue is real or not, or how people feel, it's whether or not this bug report can be turned quickly into a successful bug fix or not. If it can't, it should be closed.
+
+.. important::
+	The reason we report bugs is not to document or catalog anything that is (or might be) wrong with the software, it's to improve it. Bug reports which don't lead to successful bug fixes get in the way and prevent developers from quickly identifying bug reports which do. The goal of a bug report is to improve the software. When submitting a bug report, don't ask yourself whether it's legitimate, ask yourself if it's pertinent, simple and complete enough to lead to a bug fix.