Move troubleshooting documentation inline to where the features are
Today we have a troubleshooting page: https://docs.gitlab.com/ee/administration/troubleshooting/debug.html which contains a number of tools and helpful hints on troubleshooting GitLab. This is all centralized though, as opposed to having troubleshooting steps inline with where the rest of the features/services documentation is.
We should move have the troubleshooting information inline with where the rest of the documentation it relates to is, and can then have this page as a set of links back to that those parts of the documentation.
Troubleshooting pages
Below are the separate troubleshooting pages that we have in our products:
Link | Notes | Action needed |
---|---|---|
/debug.html |
|
Yes |
/diagnostics_tools.html | Used by Support Diagnostics tools the GitLab Support team uses during troubleshooting | No |
/elasticsearch.html | There's also another troubleshooting section in the Elasticsearch docs. They need to be merged and be moved to the ES docs themselves. The section is already big, so we might need to break into its own doc. | Yes |
/gitlab_rails_cheat_sheet.html | This was created by the Support team to have something quick to access when troubleshooting via the Rails console. If we moved it, we'd break their workflow. It seems to be fairly similar to https://docs.gitlab.com/ee/administration/troubleshooting/navigating_gitlab_via_rails_console.html, so we may need to merge those two. | Yes |
/group_saml_scim.html | As stated in the page: "These are notes and screenshots regarding Group SAML and SCIM that the GitLab Support Team sometimes uses while troubleshooting, but which do not fit into the official documentation. GitLab is making this public, so that anyone can make use of the Support team’s collected knowledge." The user troubleshooting docs are in https://docs.gitlab.com/ee/user/group/saml_sso/index.html#troubleshooting. Might be worth to discuss whether this belongs to the docs or the handbook. | Yes |
/kubernetes_cheat_sheet.html | Used by Support This is a list of useful information regarding Kubernetes that the GitLab Support Team sometimes uses while troubleshooting. GitLab is making this public, so that anyone can make use of the Support team’s collected knowledge. We can move this under https://docs.gitlab.com/charts/troubleshooting/. | Yes |
/linux_cheat_sheet.html | This is the GitLab Support Team’s collection of information regarding Linux, that they sometimes use while troubleshooting. I contains some information that we could potentially move to other places like the Networking/DNS" section, but not sure it's worth it, since it would break the Support's workflow. We can try duplicating some of that info under https://docs.gitlab.com/omnibus/settings/dns.html. | Yes |
/log_parsing.html | Contains info on log parsing mostly with jq . Can be merge into https://docs.gitlab.com/ee/administration/logs.html. |
Yes |
/navigating_gitlab_via_rails_console.html | We also have https://docs.gitlab.com/ee/administration/troubleshooting/gitlab_rails_cheat_sheet.html, so we may need to merge those two. | Yes |
/postgresql.html | Used by Support This page is useful information about PostgreSQL that the GitLab Support Team sometimes uses while troubleshooting. Contains links to other pages, and some troubleshooting tips that should not really be used by users. No need to move anything. | No |
/sidekiq.html | Should probably be moved under https://docs.gitlab.com/ee/administration/sidekiq.html. It is also in a wrong location in the docs navbar. | Yes |
/ssl.html | Contains info that could be split into the respective locations. | Yes |
/test_environments.html | Used by support. Information about using Docker images to spawn testing environments. | No |
/tracing_correlation_id.html | This talks about logs, so it should be moved under https://docs.gitlab.com/ee/administration/logs.html. | Yes |
reference_architectures/troubleshooting.html | Troubleshooting info specifically for the reference architectures. Most of those are actually duplicate entries, since we were asked to have all the reference architecture information in one place even if that meant having duplicate info. We can try and start pointing back to the respective components, like Gitaly. https://docs.gitlab.com/ee/administration/gitaly/#troubleshooting-gitaly is essentially the same as https://docs.gitlab.com/ee/administration/reference_architectures/troubleshooting.html#troubleshooting-gitaly. | ? |
operations/rails_console.html | Duplicate of https://docs.gitlab.com/ee/administration/troubleshooting/navigating_gitlab_via_rails_console.html, they should be merged. | Yes |
charts/troubleshooting | Charts related information. No need to take any action. | No |
omnibus/common_installation_problems | Omnibus-related troubleshooting. No immediate action needed. | No |