Document the differences between /help and docs.gitlab.com
The documentation hosted under an instance's /help
(for example https://gitlab.com/help) has some differences to the one hosted under the docs site (https://docs.gitlab.com).
This issue aims to document what is /help
, how it works, and how it differs from docs.gitlab.com,
/help
?
What is With /help
we refer to an instance's built-in help pages. This is the relative path that follows after GitLab's domain name, so for https://gitlab.com, that would be https://gitlab.com/help.
/help
built?
How is Every GitLab instance (no matter how you installed it) uses the gitlab-org/gitlab
repository underneath. The following files are used to render /help
:
-
app/controllers/help_controller.rb
: behavior of the/help
URLs. -
app/views/help
: views files. -
doc
: Markdown file to render. -
app/helpers/search_helper.rb
: limited search function. -
config/routes/help.rb
: routes for/help
.
There are also the helper methods that take the Markdown file as an argument and create the needed paths:
- Ruby helper
- JavaScript helper
The /help
page and its contents have various tests in place:
spec/features/help_pages_spec.rb
-
spec/helpers/releases_helper_spec.rb
: should not be there,help_pages_spec.rb
should be the only file that tests/help
. -
haml_lint/linter/documentation_links.rb
: lint checker that checks if ahelp_page_path
link is valid.
Pages in GitLab that contain the helpers which point to the Markdown files:
-
help_page_path
: Ruby helpers -
helpPagePath
: JavaScript helpers
/help
contain?
What info does The landing page of the help page contains two pieces of information:
doc/index.md
- top and right side information
With red is the extra information that is not included in the docs. If we were to not render doc/index.md
, this would be the only info shown in /help
. Basically:
- Installed GitLab version, and if you're on Enterprise or Community.
- The latest commit version and if you're "up-to-date".
- A link to the current instance configuration.
- Links to some about.gitlab resources, like getting help, version comparisons, and pricing.
/help
different from docs.gitlab.com?
How is 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. The docs site includes not only the docs under the GitLab repository, but also the docs of Omnibus, Runners, and Charts. In essence, the content of /help
is a subset of the docs site. Read more about the docs site architecture.
We publish the following doc paths to the following locations:
Project | Path | docs.gitlab.com | <instanceDomain>/help |
---|---|---|---|
GitLab | /doc |
✓ 1 | ✓ 2 |
GitLab Runner | /docs |
✓ | |
GitLab Helm Charts | /doc |
✓ | |
Omnibus GitLab | /doc |
✓ |
1 Last three versions
2 Current version of the instance only
Different Markdown engines
-
/help
: The feature set of/help
has seen little updates throughout the years. This mostly works like when we create a comment; Ruby renders HTML from Markdown on the fly./help
actually renders thedoc/
dir that is shipped with GitLab, as you can see from the controller below.- Markdown engine: CommonMark
- Built by:
-
docs.gitlab.com
: This is the static site where we take the markdown pages and we convert them to HTML, with some additional features we've building regularly.- Markdown engine: Kramdown
- Built by:
/help
Problems with - 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. gitlab-docs!346 (merged))
- 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.) 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.
/help
The path to move away from Work done in #214164 (closed) opened the path to move away from /help
. There's already the ability to redirect /help
pages to a self-hosted docs site.
There are two options to self-host the docs site:
- Current working option: self-host the docs site using the Docker images.
- Alternative option: bundle with Omnibus omnibus-gitlab!4726 (closed). This has some caveats:
- The current search implementation with Algolia will not work. It will still show you results, but the links will point to https://docs.gitlab.com. There's an open issue to explore alternatives gitlab-docs#672 (closed). An MVC is to hide search when bundling with Omnibus gitlab-docs!2033 (closed).
- All links that point to Charts, Runner, and Omnibus, will use the full URL pointing to
https://gitlab.com
. This can be solved by using the same script we use when we build the Docker files. It basically stripshttps://docs.gitlab.com
and uses relative URLs. One other option would be to make this a built-in function when Nanoc builds the site.
Related issues and epics
- Issues containing the help page label: https://gitlab.com/gitlab-org/gitlab/-/issues?scope=all&state=opened&label_name[]=help%20page
- &2883 (closed)