We currently publish the following doc paths to the following locations: | Project | Path | [docs.gitlab.com](https://docs.gitlab.com) | \<instanceDomain\>[/help](https://gitlab.com/help) | | --- | --- | --- | --- | | [GitLab](https://gitlab.com/gitlab-org/gitlab/) | [`/doc`](https://gitlab.com/gitlab-org/gitlab/tree/master/doc) | ✓ ¹ | ✓ ² | | [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner/) | [`/docs`](https://gitlab.com/gitlab-org/gitlab-runner/tree/master/docs) | ✓ | | | [GitLab Helm Charts](https://gitlab.com/gitlab-org/charts/gitlab) | [`/docs`](https://gitlab.com/gitlab-org/gitlab-runner/tree/master/docs) | ✓ | | | [Omnibus GitLab](https://gitlab.com/gitlab-org/omnibus-gitlab/) | [`/doc`](https://gitlab.com/gitlab-org/gitlab-ee/tree/master/doc) | ✓ | | ¹ Last three versions (with plans to grow that indefinitely), and additional archives available ² Current version of the instance only All links to documentation within GitLab go to a path on `/help`, however, docs.gitlab.com has far exceeded `/help` in terms of features and UX. There has long been a discussion https://gitlab.com/gitlab-org/gitlab-foss/issues/18739 about whether to deprecate `/help` and switching in-app links to docs.gitlab.com paths for a number of reasons. ## Problems with `/help` - Increasingly lacks features that exist solely in docs.gitlab.com (e.g. search, nav, table of contents, easy path to contribute issues/MRs, certain markdown rendering, styles, etc.) - We're often blocked from implementing reasonable fixes to UX issues on docs.gitlab.com due to the fix being incompatible with /help (e.g. https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/346) - Does not reflect content improvements that are deployed to docs.gitlab.com since the release. - Often slower to load pages. - For each doc page with a changed path/filename, we must leave an MD file behind with a reference to the new page, as redirects are not possible. There are 140 of these and counting. ([Example here](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/administration/build_artifacts.md).) These make it difficult to analyze and reorganize our content, and could be removed if not for /help. - It duplicates docs.gitlab.com, without offering any unique benefits. ## Work to be done ### Completed work 1. [x] Versioned docs on docs.gitlab.com, so we will be able to link out from the product to doc pages that apply to the user's current edition+version. (Versioned docs are now available, with [enhancements planned](https://gitlab.com/gitlab-com/gitlab-docs/issues/248) that will not break existing paths.) 1. [x] https://gitlab.com/gitlab-org/gitlab-docs/issues/313 So that we can easily store more and more version paths indefinitely, promote and utilize enhancements to Pages (we've gone with this over the original possibility of deploying to a new server, outside Pages). E.g. need to ensure that a link to a doc under /13.1 (and any other version) will always work. At this point, we'll stop needing to highlight the archive images of prior help versions as the main way of accessing that old help, though we can still link to the archives for folks who need them. The archives may then only be used by those who have offline users who need to host help on their local network. 1. [x] We now have per-project Pages artifact size limits, and have a 2GB limit, with a [request to increase to 10GB](https://gitlab.com/gitlab-com/gl-infra/infrastructure/issues/9019). (*Update*: Approved and increased to 10GB.) At 10GB, it means we can use pages for all minor versions of 4 GitLab versions, offering plenty of room to move forward now with our current infrastructure and decide to change our strategy later on. Axil will also ask in this request if the large deployments at some point would have any especially adverse impacts to the server or deployment times. ### Next Improve the offline documentation experience for air-gapped instances https://gitlab.com/gitlab-org/gitlab/-/issues/214164 ### On hold pending results of offline documentation planning 1. [x] https://gitlab.com/gitlab-com/www-gitlab-com/merge_requests/32709 Post a deprecation notice for /help describing the changes and requesting feedback; perhaps we mention that if you have offline users, we're interested to hear from you about our proposed solution for that. 1. [x] https://gitlab.com/gitlab-org/gitlab-docs/issues/390 Ensure docs site build process is accessible to any admin who opts to keep users offline/firewalled, i.e. without access to docs.gitlab.com. (Per Support, this is unheard of, but this is very easy to accommodate by having the go-to solution ready, just in case. E.g. we already producer Docker archive images for each help version.) Such an admin could resolve docs.gitlab.com to their preferred host. Main solution is to link to archives that one can deploy on local network. Alternative we can offer is to use our [existing docs project](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/README.md); they can build it as we do; heavier, but could work for some. Due to CI variables, unneeded embedded JS will not be included. 1. [x] https://gitlab.com/gitlab-org/gitlab/issues/27068 Remove the doc files themselves from `/help` (deprecation notice for 13.0). NOTE: Question as to whether this should happen at the same time as swapping in-app URLs, as the /help URLs would then need to be manually entered; unlikely to be of help to a user. So probably: yes, in the same release. Alternatively we can have each former /help URL display a message that "This content is now only available online at <URL>" so that old, bookmarked URLs work. ### Nice to haves 1. [ ] https://gitlab.com/gitlab-org/gitlab/issues/27067 Rewrite the home page of `/help` to offer useful links (instead of full help home page); keep /help/instance_configuration as the only other page. 1. [ ] Further improvements to the /help home page https://gitlab.com/gitlab-org/gitlab/issues/2297 (If not resolved by https://gitlab.com/gitlab-org/gitlab/issues/27067.) ### To do 1. [x] https://gitlab.com/gitlab-org/gitlab/issues/26046 Update GitLab to render doc links as `docs.gitlab.com/<version>/<edition>/<path>`. For example, a link to `<instanceDomain>/help/user/project/pages/index.md` becomes `https://docs.gitlab.com/12.4/ee/user/project/pages/index.html` ## Questions 1. We've had agreement from various parties over time, but should get a review of the latest state of the plan from Product and UX, and their help with a deprecation notice to post with 12.8 briefly summarizing this change and possibly seeking feedback from customers with offline users on our plans for how to accommodate them. **-> Some customer feedback gathered in https://gitlab.com/gitlab-org/gitlab/-/issues/214164. No changes have been implemented as of GitLab 13.2. Planning in progress.** 1. Which team should implement all of these `gitlab` issues? Engineering Productivity had been the default, as they partner with Technical Writing for general backend Engineering matters (typically on docs.gitlab itself), but perhaps this should also involve a specific stage/group, e.g. Enablement, as it's part of GitLab the product? **-> Static Site Editor team is now leading this.** 1. Does any of this need to occur in a major release (13.0), or is that merely preferable, vs. occurring in any minor release? (Or should we go with 13.1 over 13.0, so customers can upgrade to 13 and keep the /help links; i.e. it definitely wouldn't be a downside to their major upgrade?) **-> No changes for 13.0** 1. When exactly to stop including (not just deprecate) the /help copy of doc pages; same release as the links change? (Probably. The pages are of minimal value if not directly linked; there's no search on /help so users must otherwise manually browse to the page they need, or use a bookmarked URL, or replicate the path of a docs site URL.) -> **Pending result of https://gitlab.com/gitlab-org/gitlab/-/issues/214164** 1. Is it OK to simply offer Docker image archives of all help versions for those who have offline users and want to spin up their own docs.gitlab.com? Can that be the MVC and based on feedback we can choose to also offer zips of the site files? (Edit: We are in fact planning to offer zip downloads as well.) -> **Alternate solution being developed https://gitlab.com/gitlab-org/gitlab/-/issues/214164**