Docs: Make Troubleshooting information easier to find through search
Troubleshooting topics continue to be among the hardest resources for customers to find. One reason is that we might not actually provide the information the customer seeks. Another reason is because of how Search works.
Searching on docs.gitlab.com usually requires multiple steps.
- Type search text in the field.
- Select the result.
- If you did not search for the exact page title, you must CMD+F to find the title on the page, or use the right nav to find the topic.
The only way to jump to a specific heading on a page is if the headings are very clear and specific, like the .gitlab-ci.yml reference page. (Search for rules
to view the behavior.)
This issue is to discuss how we might work to make our content easier to search.
Proposal
- For pages with 5 or more troubleshooting topics, put the troubleshooting information on its own page, rather than nesting it on other pages.
- Use the Troubleshooting topic type guidance for how to format the information, the title, and the nav. (We can change this type from a "topic" type to a "page" type.)
Data
See this spreadsheet for pages that have multiple troubleshooting topics.
Edited by Suzanne Selhorn