Troubleshooting topic type
Troubleshooting topics should be the final topics on a page.
If a page has more than five troubleshooting topics, put the content on a separate page that has troubleshooting information exclusively. Name the page
and in the left nav, use the word
Troubleshooting can be one of three types.
An introductory topic
This topic introduces the troubleshooting section of a page. For example:
## Troubleshooting When working with <x feature>, you might encounter the following issues.
The title should be similar to a standard task. For example, "Run debug tools" or "Verify syntax."
This topic includes the error message. For example:
### The error message or a description of it You might get an error that states <error message>. This issue occurs when... The workaround is...
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.
Troubleshooting topic titles
For the title of a Troubleshooting reference topic:
- Consider including at least a partial error message.
- Use fewer than 70 characters.
- Do not use links in the title.
If you do not put the full error in the title, include it in the body text.
Rails console write functions
If the troubleshooting suggestion includes a function that changes data on the GitLab instance, add the following warning:
WARNING: Commands that change data can cause damage if not run correctly or under the right conditions. Always run commands in a test environment first and have a backup instance ready to restore.