Q3FY23 KR: Improve the Cloud Native install documentation to support teams that want to run GitLab in Kubernetes
Product direction background
From the Cloud Native Installation Product Direction handbook page:
We have seen significant growth in organizations adopting Kubernetes and increased interest in deploying GitLab in Kubernetes.
Our goal is for cloud-native deployments to be similar in simplicity and configuration as our Omnibus package, and surpass our Omnibus package in day 2 automation. In 2022, we hope to be able to recommend our cloud-native installation on par with our Omnibus package for simple deployments and where it is cost effective, or recommend a hybrid architecture over a pure Omnibus installation due to the benefits cloud-native can offer.
Our Omnibus installation experience is very straightforward and easy to do. We would like to replicate that ease in our Cloud Native documentation as we move further in our maturity for CNG towards lovable, even though setting up an instance of GitLab in a Cloud Native environment is inherently more complicated. Kubernetes is of growing interest for our potential customers, so making sure our Cloud Native documentation is as easy as possible is important.
Recent and ongoing docs efforts related to this KR
- Add cloud native index page
- Add GitLab Operator as a new product of the docs site
- Streamline charts documentation
- Installation and Configuration documentation improvements
- Support tabbed content on documentation pages. There is no easy way to have consolidated documentation across different installation methods, leading confusing navigation and loss of SSOT. Tabbed content was added to the Documentation roadmap (priory 2) as a capability that could address these challenges.
Related epics
- Improve experience of navigating installation, configuration, and update documentation
- Streamline charts documentation
Examples and evidence of customer or support pain points
- Customer feedback issue: gitlab#368528 (closed)
What great cloud native docs would look like
The aspiration:
What MVC docs changes could look like
Priorities within the aspiration
- Tile style organization for selecting install instructions - https://stripe.com/docs/development/quickstart
- Linear instructions that keep you in the same install page experience - https://stripe.com/docs/development/quickstart/ruby
- Perhaps expanding sections for optional steps, that would not over clutter but would keep you in the experience if you needed it
Who can help us with docs improvements
- Distribution engineers will be available to support and answer questions as needed.
Work to be done
Here is a draft of the major work so we can track it in Ally. The focus of this OKR is the content under Install with Helm chart.
We will not be able to fix everything in this OKR. However we can move content, apply consistent language, and start organizing the experience so it's more straightforward.
-
Come up with the long and short name for the chart gitlab!95417 (merged) -
Apply them consistently throughout.
-
-
Come up with usage and capitalization for cloud native
gitlab!95417 (merged)-
Use it consistently throughout.
-
-
Suzanne: Edit the top two pages (this and this) for style, language, consistency. -
Axil: Change this page title to something about configuration. Configure the GitLab chart
? gitlab-org/charts/gitlab!2795 (merged) -
Suzanne: Add the command-line install options page to the global nav in the Install
area. -
Axil: Update the title of the Quick Start page so it doesn't say Guide
but instead explains what this page is--how to deploy on GKE. gitlab-org/charts/gitlab!2736 (merged) -
Axil: Add the Quick Start page to the global nav. gitlab-docs!3042 (merged) -
Axil: Combine the Required tools page with the Cloud cluster preparation page. Call it Prerequisites for installing the GitLab chart
(or whatever we decide to call the chart). gitlab-org/charts/gitlab!2717 (merged) -
Axil: Take the information from the deploy page, which is really prereq information, and put it on the Required tools page. -
Suzanne: Rename the Deployment Guide page to something more active. Either Deploy the GitLab chart
orInstall the GitLab chart
. -
Axil: Move the Upgrade, Backup and restore, and Migrate listings in the global nav to the left one level. These entries should be at the same level as Install
. gitlab-docs!3060 (merged) -
Axil: Rename the Upgrade page to something like, Upgrade the GitLab chart
(rather thanUpgrade Guide
). gitlab-org/charts/gitlab!2734 (merged) -
Axil: Make the upgrade titles active. gitlab-org/charts/gitlab!2734 (merged) -
Axil: Put the Version mappings page into the pre-req area of the global nav. gitlab-docs!3058 (merged) -
Axil: Rename Troubleshooting page title to be more descriptive. Troubleshooting the GitLab chart
gitlab-org/charts/gitlab!2751 (merged) -
Axil: For the pages in the advanced
section, make the page titles parallel. They need to be phrased in the same way, and have the same capitalization. Right now, here is what those page titles look like:Bringing your own images External PostgreSQL database Configure this chart with External Gitaly Configure this chart with External GitLab Pages Configure This Chart with Mattermost Team Edition External NGINX Ingress Controller External object storage Configure this chart with External Redis GitLab with FIPS-compliant images GitLab Geo Using TLS between components Managing Persistent Volumes GitLab with UBI-based images
-
Axil: Take this upgrade topic and the ones below and move them into a new page. (asked clarification in #642 (comment 1068143535)) gitlab-org/charts/gitlab#3949 -
Axil: Give the advanced configuration page a better/more descriptive title. I assume it's more about configuration? gitlab-org/charts/gitlab#3950 -
Axil: Rename these page titles to match the others in the area gitlab-org/charts/gitlab#3951: -
Using the GitLab-Migrations Chart (lowercase for
chart
) (and maybe the name is not fully correct?) -
Toolbox - Should be
Using the Toolbox chart
. -
Using the GitLab Webservice Chart (lowercase
c
) -
Using MinIO for Object storage - add
chart
? -
Using NGINX - add
chart
?
-
Using the GitLab-Migrations Chart (lowercase for
-
If time, run Vale and edit pages for grammar, language, and style. gitlab-org/charts/gitlab#3952 -
Take the info from this redis topic and make it its own page. Add the page to the global nav with the others. -
Review the global nav to ensure it matches the page titles. gitlab-docs#1304 -
Review the list of pages not in the nav and ensure that the ones related to chart installation are in the nav, and that the page titles are parallel/correct. gitlab-docs#1304