readthedocs · benjaoming · Jan 27, 2023 · Jan 18, 2023 · Jan 18, 2023 · Jan 18, 2023
diff --git a/docs/user/build-troubleshooting.rst → docs/user/guides/build-troubleshooting.rst b/docs/user/build-troubleshooting.rst → docs/user/guides/build-troubleshooting.rst
@@ -1,8 +1,12 @@
-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.
+
+.. tip::
+
+   Please help us keep this section updated and contribute your own build errors and resolutions.
+   Send in helpful comments or ideas 💡 to [email protected]
+   or contribute directly by clicking :guilabel:`Edit on GitHub` in the top right corner of this page.
 
 
 Git errors
@@ -60,7 +64,6 @@ Permission denied (publickey)
    - ``https://bitbucket.org/<username>/<repo>/admin/access-keys/``
 
 
-
 ERROR: Repository not found.
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

diff --git a/docs/user/guides/build-using-too-many-resources.rst b/docs/user/guides/build-using-too-many-resources.rst
@@ -1,11 +1,20 @@
-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 Read the Docs,
+you may want to have a look at the most common issues that slow down builds.
 
-.. note:: The current build limits can be found on our :doc:`/builds` page.
+.. note::
+
+   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 :doc:`/builds` page.
+
+.. tip::
+
+   Please help us keep this section updated and contribute your own performance improvements.
+   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.
 
 Reduce formats you're building
 ------------------------------

diff --git a/docs/user/guides/troubleshooting/index.rst b/docs/user/guides/troubleshooting/index.rst
@@ -0,0 +1,14 @@
+How to troubleshoot specific issues
+-----------------------------------
+
+In the following guides,
+you can learn how to fix specific common problems.
+
+.. 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>
diff --git a/docs/user/index.rst b/docs/user/index.rst
@@ -97,6 +97,7 @@ to help you create fantastic documentation for your project.
    /guides/authors
    /guides/administrators
    /guides/developers
+   Troubleshooting </guides/troubleshooting/index>
    /examples
 
 
@@ -158,7 +159,6 @@ and some of the core features of Read the Docs.
 
    /builds
    /build-customization
-   /build-troubleshooting
    /environment-variables
    /badges