Roadmap for improving self-managed users' Help experience
This issue is related to Q4FY2022 KR: Determine how to improve/remedy the /help experience for GitLab users and is for directed discussions about the roadmap for improving self-managed users' Help experience with GitLab. Conversations not relating to this roadmap should be directed back to the parent OKR issue.
Issue Description
This issue is to discuss and approve a roadmap for improving the self-managed users' GitLab product documentation help experience. While there are many opportunities to help users, 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 would need to be done by developers, but that work should be minimal and potentially able to be scheduled in without too many issues.
-
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)). -
Auto-populate the GitLab Documentation pages URL field with
https://docs.gitlab.com
. -
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.
After approval
After this roadmap is functionally complete, this issue will be closed, and the roadmap will be moved to the main Q4FY2022 KR: Determine how to improve/remedy the /help experience for GitLab users OKR issue.