Improve version navigation

Update: The latest discussion is now in the following issue, and this issue may need to be closed: #268 (closed)

Background

Currently, visitors of the docs.gitlab.com home page (and pages found through internal and external searches) access pages under https://docs.gitlab.com/ee/ & https://docs.gitlab.com/ce/, which display docs rendered from the repos' master branches.

We currently publish the last three releases' docs under version-numbered paths (`docs.gitlab.com/XX.Y/*'). These are available as online "archives" and we recently added a Versions drop-down that links to the home page of those archived sites, along with the /archives page to access even earlier docs.

Problems to solve

1. If a user is running an older GitLab release (e.g. 2 minor versions back), it's a poor experience to find a topic of interest in the docs that shows incorrect info which pertains to a later version than they're running.
2. If a user uses the version drop down, the menu brings them to the home page of the version they select, not the equivalent [earlier-versioned] page to the original page.
3. If a user is using the latest GitLab release, they are seeing a mix of doc pages for that release and the next release. (I.e. their GitLab instance may not yet have caught up to the doc they're viewing, which we recently published to master.)
4. It's not clear that you're viewing docs from master by default, and the current dropdown offers no indication of what version you're currently set to (or the version of the doc you're currently looking at).
5. Accommodate the fact that a gitlab.com user may not be aware which GitLab version they're on; they just need docs pertaining to whatever release is currently deployed on gitlab.com
6. We currently only allow search of the 'master' docs

Needs

1. From home page (/) continue to show latest release by default
2. Users should know what version they're looking at:
   1. highlight the "selected" version in menu https://gitlab.com/gitlab-com/gitlab-docs/issues/270
   2. Rename menu to simply vXX.Y (the current version)?
   3. At least for docs on stable/master, mention when they were updated? Add frontmatter that includes version and then conditionally shows a message or use time/date stamp? (Can we automatically include time/date based on git data? We already allow manual inclusion of date/time in frontmatter.)
   4. Offer a tooltip next to or inside the menu explaining versions
3. Have the ability to easily switch versions, and when doing so from a doc page, jump to the same doc page in the previous version; if it doesn't exist in the previous version, have a better experience than just hitting a 404. (Need separate 404 issue; possible auto-search based on URL in 404 page)
4. Universal banner that warns if not on the latest version https://gitlab.com/gitlab-com/gitlab-docs/issues/181 ( How others do it: https://docs.docker.com/v17.06/ http://dokku.viewdocs.io/dokku/getting-started/installation/ ) Mike/Axil have decided to strike this given the other improved versioning features
5. Search: Enable faceted search or version specific search by adding each version's site as a separate index OR otherwise using metadata to define versions. (Consult Algolia docs and support.) https://gitlab.com/gitlab-com/gitlab-docs/issues/182

Proposal

High-level summary:

• Launch the directory for the new version (e.g. 11.9) to docs.gitlab.com around its first RC. (docs.gitlab.com/11.9).
• Visitors to docs.gitlab.com/ display the latest release (so 11.8), instead of master. Even though 11.8 still exists (and is identical to /, as we want each version path to persist before and after the release. However, we will not let search engines index the versioned paths, only /.
• Keep the top nav updated, so that users on GitLab.com know if they need to switch to the RC, which will also be labeled GitLab.com.
• Upon the 22nd, switch / to 11.9.
• Continually deploy master to docs.gitlab.com/dev, instead, where they are accessible if needed (e.g. perhaps for feature-flagged features https://gitlab.com/gitlab-org/gitlab-ce/issues/56813)?

Details:

(Draft. Check once confirmed as official proposal.)

1. TODO: When to first deploy next-version stable branch to doc site in its own path: some time between 1st of month and first RC. Working plan: Do this on first RC. we can have an MR ready for this that gets merged when RC is released. In coordination with release managers.
   1. TODO: There is no stable branch for Runner prior to the 7th; how do we deploy a version of docs before the 7th without it, if at all?
   2. Create stable branch docker file (pulls all the needed branches from the different projects, and builds docker image for the release)
   3. Change dropdown and archive previous version
   4. E.g. https://gitlab.com/gitlab-com/gitlab-docs/merge_requests/379 but sooner
2. Redeployments of next-version: hourly/regularly automatically as we have been with master->docs root path
3. On release of this version to GitLab.com -- Update drop-down menu to indicate that this is the GitLab.com version
4. On version’s release (22nd)
   1. Stop deploying from stable
   2. Move this version to root path / but leave it at XX.Y path
      1. Leverage existing canonical meta tag to the XX.Y docs so that google points to the / docs.
      2. How to have docs at both paths: symlinks. TODO: How to create this for all help paths in one batch.
   3. Further deployments of this version can now only occur manually by re-running pipeline.
5. Continually deploy dev to master.

This yields 6 online versions, but 7 paths -- one served via symlinks. This could cause space related issues and be one of multiple reasons to migrate off Pages to our own server.

TODO: Blocking questions/issues to resolve:

• Diagram for clarity in further conversations with teams (early draft) @mikelewis
• Charts - Can we have docs at the GitLab version path (e.g. 12.0) with clarity in the docs (version drop down? banner) what Charts version the user is looking at?
• Runner - What docs can we include, if any, before the freeze when we a new GitLab version path? What Runner docs are live before (if any) and after the Runner release?
• Space related issues. We can auto compress images, but it only gets us so far. What’s our real max on Pages and can we request more? Even w/o space issues, would this move enable us to do the symlinks and redirects as needed, and therefore certainly be worthwhile?
• If needed: Move to new server (@axil) - Before or after this change?

What does success look like, and how can we measure that?