Make troubleshooting more clear

Author: spoorcc

doc/troubleshooting.rst

@@ -3,23 +3,58 @@
 Troubleshooting
 ===============
 
-Although we do our best, *Dfetch* can always do something unexpected.
-A great deal of *Dfetch* functionality is dependent on plain-old command line commands.
+Sometimes *Dfetch* may not behave as expected. This is could be because it relies on
+standard command-line tools such as ``git`` to be available on your system. This section will help you
+diagnose problems and understand what is happening behind the scenes.
 
-First of all, it is important to see what tools the system has.
-This can be seen with :ref:`dfetch environment<environment>`.
+Step 1: Check your environment
+------------------------------
 
-Each command *Dfetch* performs and its result can be shown with increasing the verbosity
-with the `-v` flag. For example, if an :ref:`dfetch import<import>` is giving strange results, re-run it with::
+Before anything else, it's helpful to see which tools *Dfetch* can detect on your system.
+This shows missing or incompatible dependencies. Run:
+
+.. code-block:: bash
+
+    dfetch environment
+
+Compare the output to the expected tools your commands require.
+
+.. asciinema:: asciicasts/environment.cast
+
+Step 2: Use verbose mode
+-----------------------
+
+If a specific *Dfetch* command gives unexpected results, run it with the ``-v`` flag
+to see exactly what *Dfetch* is doing:
+
+.. code-block:: bash
 
     dfetch -v import
 
-Reporting issues
-----------------
-We are glad to help, if you you are stuck, either create an issue_ on github or contact us through gitter_!
+Verbose output shows each command *Dfetch* executes and its result, making it easier
+to spot errors, missing tools, or other issues.
+There can be various issues with for instance contacting or authenticating with the remote
+repository or with local settings. By running the ``git`` or ``svn`` command in isolation
+the issue can be shown more clearly.
+
+Step 3: Reporting issues
+------------------------
+
+If you cannot resolve a problem, we're happy to help! Check for any existing `GitHub Issues`_.
+When reporting an issue, please include:
+
+1. The output of ``dfetch environment``
+2. The verbose output of the failing command (``dfetch -v <command>``)
+3. Your operating system and shell information
+
+You can report issues via:
+
+- `GitHub Issues`_
+- `Gitter`_ community chat
+
+.. _`GitHub Issues`: https://github.com/dfetch-org/dfetch/issues
+.. _`Gitter`: https://gitter.im/dfetch-org/community
 
-.. _issue: https://github.com/dfetch-org/dfetch/issues
-.. _gitter: https://gitter.im/dfetch-org/community
 
 Security issues
 ----------------