Q4FY2022 KR: Determine how to improve/remedy the /help experience for GitLab users
To provide a better experience for end users (regardless of if they're self-managed or a user of GitLab.com), how documentation is provided to users needs to be improved.
Platform behavior and issues
Currently, the default behavior of how product documentation is accessed depends on whether GitLab is self-managed or is on GitLab.com:
- GitLab.com - Users who attempt to click links in the interface are taken to their docs.gitlab.com locations for the information. The
/help
page is accessible, but clicking documentation links on the page display docs.gitlab.com results. - Self-managed GitLab - Users who attempt to click links in the interface are taken to product documentation pages served from the
/help
directory for the product. The/help
page is accessible, and is seen as the method for users to browse the product documentation (if they don't use the in-application links).
This behavior is seen as deficient, as it provides a separate set of experiences between installation methods. It also presents an incomplete and outdated experience for self-managed users, as the Markdown rendering engine is different from that of the GitLab.docs site (and has less functionality), and there's no search function (along with other issues).
Timeline for /help replacement process
The primary goal of this effort is to create a common experience for all users, but SaaS and self-managed. This roadmap does not include adding certain SaaS-only features to self-managed Help (like search) -- those will happen in separate issues.
These steps build off of the work that's already been done to research the differences between the self-managed and SaaS product documentation experiences, along with the work Axil completed to create installation instructions for a self-hosted product documentation site.
Initial steps
These items can be accomplished at this point with little to no additional planning. Some work needs to be done by developers, but that work should be minimal and potentially able to be scheduled in without too many issues.
-
IN PROGRESS Update product documentation to better support installing and updating your own local product documentation site. (#517 (moved))
- Refine the information at https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/doc/help_page/self_host.md.
- Ensure the “self-hosting your docs” links are integrated into the installation instructions for self-managed GitLab installations.
- Ensure directions to update your self-hosted docs are included in any update instructions for self-managed GitLab installations.
-
Update the docs release process to include adding deprecated versions to
redirects.yaml
as splat redirects (see proposal at #515 (comment 756995696)). -
Deploy an archives Docs site to host old GitLab docs versions, to help self-managed users of older versions still be able to find relevant help for their version. This work should happen concurrently with the work in the previous step to change the default Docs URL. (Issue: #523 (closed))
-
Auto-populate the GitLab Documentation pages URL field with
https://docs.gitlab.com
. (Issue: gitlab#350671 (closed)) -
Remove product documentation from
/help
page. (Issue: gitlab#27067)- Goal would be to leave the top paragraph about GitLab, along with the commit info, instance configuration, and GitLab tier feature comparison links, and to remove the content already found on https://docs.gitlab.com/ee/.
-
Update in-app ? drop-down links that relate to help information:
- Change the ? > Help link in GitLab to point to the GitLab Documentation pages URL field entry.
- Create a ? > Instance information link that goes to
/help
.
-
Rename
/help
feature to/info
. Also, set up a redirect behind the scenes to make/help
requests go to/info
.
(The final two steps can potentially be combined. For example, the issue to add an Instance information link could also be the issue to rename /help
to /info
, if it's more convenient.)
Follow-on steps
These items may need additional planning, or notable amounts of work from other GitLab teams:
-
Incorporate option to install self-hosted docs into GitLab installation methods.
- Expectation is that this would be a selectable option that would allow someone to install the GitLab docs in a specific location.
- This option should auto-update the Documentation pages URL field in GitLab with the correct docs location.
-
Remove the product documentation from the GitLab installer.
OKR Progress
-
Collect and review materials and discussions that have happened up to this point. -
Identify possibilities for next steps and requirements -
Present different courses of action to TW Leadership -
Create a follow-on plan based on the selected plan, based on what's selected, availability, and resources
Resources
Work and discussions have been happening about this topic for some time, and this section contains a list of issues, epics, and MRs that relate to this topic:
Epics
- Documentation Roadmap (&4602)
- Host the docs site locally (&2883 - closed)
- Use Docs site paths for GitLab UI help links in... (&693 - closed)
Issues
- Roadmap for improving self-managed users' Help experience (#515 (closed))
-
Document the differences between /help and docs.gitlab.com(gitlab#331286 (closed)) -
Document and test process for building doc site on your own server(gitlab-docs#390 (closed)) - Improve the offline documentation experience for air-gapped instances (gitlab#214164 (closed))
- Update /help home page to drop the docs readme content, clarify help resource links (gitlab#27067)
-
Stop packaging /doc pages with GitLab under /help(gitlab#27068 (closed)) -
Change the path of /help links in the UI to point to public docs site and/or locally hosted docs site(gitlab#26046 (closed)) - Is the Help page the right place to notify about updates and config information? (gitlab#215585)
- Understanding the requirements and limitations for bundling GitLab Docs with the Omnibus package (gitlab-docs#817 (closed))
MRs
-
Allow to setup Documentation pages URL for help pages redirects(gitlab!71737 (merged)) - Draft: Hide search when docs are shipped with Omnibus (gitlab-docs!2033 (closed))
- Draft: Add an option to install gitlab-docs service with Omnibus (omnibus-gitlab!4726 (closed))
Documentation links
Additional resources