[gnome-builder] doc: add documentation on basic troubleshooting

[Christian Hergert <chergert src gnome org>]

commit 7b5f4c3cbafb62f20c74311aec3dd71779111d30
Author: Christian Hergert <chergert redhat com>
Date:   Mon Jun 19 14:16:52 2017 -0700

    doc: add documentation on basic troubleshooting
    
    This can be a useful first step to directing people to help themselves.

 doc/index.rst           |    1 +
 doc/installation.rst    |    1 +
 doc/troubleshooting.rst |   61 +++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 63 insertions(+), 0 deletions(-)
---
diff --git a/doc/index.rst b/doc/index.rst
index be6bd35..4cbcc41 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -21,5 +21,6 @@ Contents
    projects/index
    plugins/index
    howto/index
+   troubleshooting
    contributing/index
    credits
diff --git a/doc/installation.rst b/doc/installation.rst
index 7a4fcf8..1c97baa 100644
--- a/doc/installation.rst
+++ b/doc/installation.rst
@@ -18,6 +18,7 @@ The preferred installation method for Builder is `via Flatpak`_.
 This provides a bandwidth efficient and safe to use installation method that can be easily kept up to date.
 It is also the engine behind Builder's powerful SDK!
 
+.. _via_flatpak:
 
 via Flatpak
 -----------
diff --git a/doc/troubleshooting.rst b/doc/troubleshooting.rst
new file mode 100644
index 0000000..c8260f6
--- /dev/null
+++ b/doc/troubleshooting.rst
@@ -0,0 +1,61 @@
+###############
+Troubleshooting
+###############
+
+If you are having trouble with Builder you can help us help you by trying to do some basic troubleshooting.
+Here are some steps you can go through to try to discover what is going wrong.
+
+Verbose Output
+--------------
+
+You can increase the log verbosity of Builder by adding up to four ``-v`` when launching from the command 
line.
+
+.. code-block:: sh
+
+   # If running from flatpak
+   flatpak run org.gnome.Builder -vvvv
+
+   # If using distribution packages
+   gnome-builder -vvvv
+
+Support Log
+-----------
+
+Builder has support to generate a support log which can provide us with details.
+From the application menu, select “Generate Support Log”.
+It will place a log file in your home directory.
+
+Counters
+--------
+
+Builder has internal counters which can be useful to debug problems.
+Use the command bar (activated by ``Control+Enter``) and type “counters” followed by ``Enter``.
+This will bring up a new window containing the current values of the counters.
+
+If Builder has locked up, you can access the counters from outside of Builder.
+The command line tool ``dazzle-list-counters``, can be used to access the counters.
+
+.. code-block:: sh
+
+   dazzle-list-counters `pidof gnome-builder`
+
+.. note:: When running Builder from Flatpak, we do not currently expose the counters to the host. Use 
``flatpak enter $PID /bin/bash`` to enter the mount namespace and then run ``dazzle-list-counters``.
+
+Test Builder Nightly
+--------------------
+
+If you are running the stable branch or an older distribution package, please consider trying our Nightly 
release to see if the bug has already been fixed.
+Doing this before reporting bugs helps reduce the amount of bug traffic we need to look at.
+We'll usually ask you to try Nightly anyway before continuing the troubleshooting process.
+
+See :ref:`installing from Flatpak<via_flatpak>` for installation notes.
+
+File a Bug
+----------
+
+We can help you troubleshoot!
+File a bug if you're stuck and we can help you help us.
+
+See the `Builder Bugzilla`_ for creating a bug report.
+
+.. _`Builder Bugzilla`: https://bugzilla.gnome.org/enter_bug.cgi?product=gnome-builder&component=general