Add latest changes from gitlab-org/gitlab@15-3-stable-eev15.3.0-rc42

1 files changed, 37 insertions, 24 deletions

diff --git a/doc/development/documentation/structure.md b/doc/development/documentation/structure.md
index a02046d4466..a5d1290a17a 100644
--- a/doc/development/documentation/structure.md
+++ b/doc/development/documentation/structure.md
@@ -148,35 +148,60 @@ Avoid these heading titles:
 
 ## Troubleshooting
 
-Troubleshooting can be one of two categories:
+Troubleshooting topics should be the last topics on a page.
 
-- **Troubleshooting task.** This information is written the same way as a [standard task](#task).
+Troubleshooting can be one of three categories:
+
+- **An introductory topic.** This topic introduces the troubleshooting section of a page.
+  For example:
+
+  ```markdown
+  ## Troubleshooting
+
+  When working with <x feature>, you might encounter the following issues.
+  ```
+
+- **Troubleshooting task.** The title should be similar to a [standard task](#task).
   For example, "Run debug tools" or "Verify syntax."
-- **Troubleshooting reference.** This information has a specific format.
 
-Troubleshooting reference information should be in this format:
+- **Troubleshooting reference.** This information includes the error message. For example:
 
-```markdown
-# Title (the error message or a description of it)
+  ```markdown
+  ### The error message or a description of it
 
-You might get an error that states <error message>.
+  You might get an error that states <error message>.
 
-This issue occurs when...
+  This issue occurs when...
 
-The workaround is...
-```
+  The workaround is...
+  ```
 
-If multiple causes or workarounds exist, consider putting them into a table format.
+  If multiple causes or workarounds exist, consider putting them into a table format.
+  If you use the exact error message, surround it in backticks so it's styled as code.
+
+If a page has more than five troubleshooting topics, put the content on a separate page that has troubleshooting information exclusively. Name the page `Troubleshooting <featurename>`.
 
 ### Troubleshooting headings
 
-For the heading:
+For the heading of a **Troubleshooting reference** topic:
 
 - Consider including at least a partial error message.
 - Use fewer than 70 characters.
 
 If you do not put the full error in the title, include it in the body text.
 
+### Related topics
+
+If inline links are not sufficient, you can create a topic called **Related topics**
+and include an unordered list of related topics. This topic should be above the Troubleshooting section.
+
+```markdown
+# Related topics
+
+- [Configure your pipeline](link-to-topic)
+- [Trigger a pipeline manually](link-to-topic)
+```
+
 ## General heading text guidelines
 
 In general, for heading text:
@@ -272,18 +297,6 @@ If you need to add more than one task,
 consider using subsections for each distinct task.
 ```
 
-### Related topics
-
-If inline links are not sufficient, you can create a topic called **Related topics**
-and include an unordered list of related topics. This topic should be above the Troubleshooting section.
-
-```markdown
-# Related topics
-
-- [Configure your pipeline](link-to-topic)
-- [Trigger a pipeline manually](link-to-topic)
-```
-
 ### Topics and resources pages
 
 This page has a list of links that point to important sections