Docs: Add new section "How-to / Troubleshooting" and move 2 existing troubleshooting pages (#9914)

* Relabel Build Troubleshooting as how-to and update introduction to a tip admonition

* Add new level "how-to guides / troubleshooting" with 2 troubleshooting themes

* Fix up introduction to slow builds troubleshooting

* Add a tip box for the build issues page as well, slightly rephrased

* Add suggestion for "Edit on GitHub"

* refinement to "terminated by Read the Docs"

* replace spoken word with written word

* Apply suggestions from code review

Co-authored-by: Eric Holscher <[email protected]>

* Reuse contribution :tip: box, addresse @ericholscher comments

---------

Co-authored-by: Eric Holscher <[email protected]>

Author: benjaoming

docs/user/faq.rst

@@ -34,7 +34,7 @@ you can use an important word or message from the error to search for a solution
 
 .. seealso::
 
-   :doc:`/build-troubleshooting`
+   :doc:`/guides/build-troubleshooting`
       Common errors and solutions for build failures.
 
    Other FAQ entries

docs/user/build-troubleshooting.rst renamed to docs/user/guides/build-troubleshooting.rst

@@ -1,8 +1,7 @@
-Build troubleshooting
-=====================
+Troubleshooting build errors
+============================
 
-This section is very specific and may change over time.
-Please help us keep it updated and contribute your own build errors and resolutions.
+.. include:: /shared/contribute_to_troubleshooting.rst
 
 
 Git errors
@@ -60,7 +59,6 @@ Permission denied (publickey)
    - ``https://bitbucket.org/<username>/<repo>/admin/access-keys/``
 
 
-
 ERROR: Repository not found.
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/user/guides/build-using-too-many-resources.rst

@@ -1,11 +1,14 @@
-My Build is Using Too Many Resources
-====================================
+Troubleshooting slow builds
+===========================
 
-We limit build resources to make sure that users don't overwhelm our build systems.
-If you are running into this issue,
-there are a couple fixes that you might try.
+In case you are waiting a long time for your builds to finish
+or your builds are terminated by exceeding general resource limits,
+this troubleshooting guide will help you resolve some of the most common issues causing slow builds.
 
-.. note:: The current build limits can be found on our :doc:`/builds` page.
+Build resources on Read the Docs are limited to make sure that users don't overwhelm our build systems.
+The current build limits can be found on our :ref:`Build resources reference <builds:Build resources>`.
+
+.. include:: /shared/contribute_to_troubleshooting.rst
 
 Reduce formats you're building
 ------------------------------

docs/user/guides/troubleshooting/index.rst

@@ -0,0 +1,14 @@
+Troubleshooting guides
+----------------------
+
+In the following guides,
+you can learn how to fix common problems using Read the Docs.
+
+.. File locations are a bit odd here because of legacy.
+.. We will move files to new locations and create redirects in a later refactor
+
+.. toctree::
+   :maxdepth: 1
+
+   Build errors <../build-troubleshooting>
+   Slow builds <../build-using-too-many-resources>

docs/user/index.rst

@@ -96,6 +96,7 @@ to help you create fantastic documentation for your project.
    /guides/authors
    /guides/administrators
    /guides/developers
+   Troubleshooting </guides/troubleshooting/index>
    /examples
    /faq
 
@@ -159,7 +160,6 @@ and some of the core features of Read the Docs.
 
    /builds
    /build-customization
-   /build-troubleshooting
    /environment-variables
 
    /support

docs/user/shared/contribute_to_troubleshooting.rst

@@ -0,0 +1,5 @@
+.. tip::
+
+   Please help us keep this section updated and contribute your own error resolutions, performance improvements, etc.
+   Send in your helpful comments or ideas 💡 to [email protected]
+   or contribute directly by clicking :guilabel:`Edit on GitHub` in the top right corner of this page.