Accommodate offline users after help links switched to docs.gitlab.com site
Problem to solve
If we update help links from inside GitLab CE/EE to their equivalent paths on docs.gitlab.com (i.e. deprecate the <instanceDomain>/help
path), this will affect the small subset of users who use GitLab while they are not connected to the internet.
Most solutions to this involve leaving the docs in place on the GitLab instance at /help, allowing such users to visit that copy of the content, instead. That content will be missing some features that we are only able to provide on the site, like the rendering of a table of contents, and working links to other top-level paths outside of /ee or /ce such as /omnibus and /runner.
Target audience
Users who are able to connect to their GitLab instance but not the internet or otherwise cannot access docs.gitlab.com.
Further details
This helps toward the goal of allowing a single app for the DevOps lifecycle for any kind of user regardless of environment. Given that we are already building /help with the product, with a few changes, we can make the app easier to use for offline users (or prevent a degradation of their experience) while vastly improving the experience for everyone else by further leveraging docs.gitlab.com.
Proposal
The optimal solution may be
-
Allow the admin to toggle the help path
- Allow them to use
<instanceDomain>/help/
instead ofdocs.gitlab.com/<edition>/<version>/
.- But we'd need to account for how to handle future links we add in the UI to other top-level paths like /runner and /omnibus that are not included in /help and only on the doc site. And perhaps avoid relative links in CE/EE docs to these other top level paths, so that users in /help will at least have the option to go online and have a working link.
- Also allow them to use a custom path. This allows them to build the doc site on their network or user's local machine.
- This will require improved build instructions and perhaps the ability to toggle off items that will only work on docs.gitlab.com, such as comments.
- Allow them to use
What does success look like, and how can we measure that?
- Positive feedback from GitLabbers who consult with customers or prospects in such offline / highly secure environments.
Links / references
- https://gitlab.com/gitlab-org/gitlab-ce/issues/18739
- https://gitlab.com/gitlab-org/gitlab-ce/issues/56101
Note: We can add further gitlab-docs project needs to the same epic once the project's move is complete.