Skip to content

Improve the offline documentation experience for air-gapped instances

Problem to solve

The primary method for accessing the GitLab application’s documentation (along with docs for Runner, Omnibus, and Charts) is docs.gitlab.com. Multiple GitLab versions' docs are available using a version slector in the page header.

The GitLab application docs for an instance’s specific version are also packaged with the application and available under yourinstance.example.com/help, commonly called “/help” ("slash-help"). Example: gitlab.com/help.

While both outputs use markdown files from the gitlab repository as their content source, these sites are generated differently and have different feature sets.

/help lacks features and has not been well maintained for resource allocation reasons. For example, certain styles do not properly render. Many features (includes, redirects, search) would need to be implemented or enhanced differently for each, more than doubling the required development, and typically causing a further divergence in UX between the two. (Being blocked from implementing includes is preventing various content initiatives the team would like to undertake in order to reuse content without duplication.) This epic covers the disparity between these resources in greater depth: &693 (closed).

All links within the GitLab UI to relevant documentation have pointed to the local /help copy of a page. There is a long-standing proposal &693 (closed) (with various prerequisite work completed) to change this behavior and point all links from the UI by default to the equivalent page on docs.gitlab.com.

However, in doing so, we cannot simply cease production of /help, due to the importance of offline access to documentation among air-gapped customers (discussed in this thread).

Intended users

Any roles operating in air-gapped environments.

Further details

Proposal

Thus far, discussions on how to continue to serve air-gapped customers has come down to one of two types of solutions:

  1. Offer the documentation site as a standalone service that an administrator can opt to deploy on their GitLab server or otherwise on their network. This could involve including a docs.gitlab.com container within the Omnibus package.
  2. Upgrade the methods for building /help to be more closely in line with that of docs.gitlab so that there's feature parity between the two.

In either case, we would bring the new build process more closely in line with the docs.gitlab.com build process and ensure that the two outputs are closer in features, though some would still be unavailable offline, such as commenting.

Either solution would likely require:

  1. An option in GitLab to continue to point all doc links to /help or <customdomain> instead of docs.gitlab.com, the new default. This option could be specific to the docs and/or a single option to indicate that it's an air-gapped instance, which would carry through to all features that are capable of adapting to such an environment #32328 (closed).
  2. A solution for offline search. The docs.gitlab.com site currently uses Algolia which makes requests over the web for each query gitlab-docs#672 (closed).
  3. A new build process for offline docs, which would be as close as possible to that of docs.gitlab.com (e.g. using the same markdown rendering engine) but taking into account any differences required (e.g. preventing the display of the versions dropdown and commenting feature; handling 404s/redirects; etc.)
  4. Consider whether all versions should be made available (which would result in a large package) or if the customer can pick a version? How do their docs stay in sync with their GitLab version?
  5. Consider whether to begin to also make the Runner, Omnibus, and Charts project docs available offline. (These are currently unavailable in /help.) Is it easy to simply offer the Runner docs version that matches the current GitLab version?

An initial MVC could add the setting in #1 while keeping /help as-is and planning the remaining offline help enhancements. In the interim, a phased rollout plan could ensure that that air-gapped customers who upgrade GitLab aren't surprised by a new default of help links that point to docs.gitlab, but eventually this becomes the default for all who have not manually selected to continue using offline help.

Customers/prospects with potential interest

Permissions and Security

Documentation

Availability & Testing

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

What is the type of buyer?

Is this a cross-stage feature?

Links / references

Edited by Susan Tacker