Develop cross-repo global docs navigation mechanism

Proposal

The GitLab documentation site displays documentation from the repositories for GitLab, Omnibus, Charts, and Runner. Each repository has its own global nav file, with its own menu hierarchy, available from:

• https://docs.gitlab.com/ee/README.html
• https://docs.gitlab.com/runner/
• https://docs.gitlab.com/charts/
• https://docs.gitlab.com/omnibus/README.html

Users, however, don't get utility from this structure. Exposing this docs repo structure to users doesn't make documentation easier to use -- on the contrary, in my opinion it makes for a more complicated interface that hides information from users.

The GitLab documentation should instead have a single, global navigation experience, where information from the separate repos are listed within a single global nav experience. With some level of automation and good planning, I believe this is possible.

One method could be as follows: in the https://gitlab.com/gitlab-org/gitlab-docs/-/tree/master/content/_data directory, one of the -nav.yaml files would be chosen as the main file. All updates regarding documentation hierarchy and display in the global nav would be made to that file. Some other mechanism would at some point reconcile those changes to the other 3 -nav.yaml files, fixing the URLs as needed to ensure that links work as the user jumps between repos and documentation pages hosted by them. For example, if default-nav.yaml was selected as the main file, the omnibus-nav.yaml file would be identical to the main file, but links to pages in the GitLab repo would need to be changed to include the https://docs.gitlab.com/ee prefix.

An alternate method could be to modify all of the files to be exact, but to always use absolute link URLs for all files. That way, there's no automation required for fixing links... it's just copying the files to always be exact (with each file containing the absolute URLs, meaning the links would work regardless of the location of the user).

These are potential options, but we need to determine if this is a viable possibility. Getting our site visitors to a "one GitLab documentation experience" could be worth the effort -- we just need to determine what that effort is.

Deliverable

The deliverable of this issue is whether or not having a common end-user experience for the global navigation on docs.gitlab.com is possible, and if so, what would be required to implement and maintain it.