Clean up documentation
The docs need an overhaul if we are to deploy them under docs.gitlab.com.
Overview
Here's a list of the steps one has to take once on the landing page in order to properly install GitLab:
- Visit the landing page which is just a list of pages
- I want to install so I click on installation
- As a first step, I go to requirements. there's a link with some helm docs
- I read the helm docs, there's no indication where to go next
- I go back to the installation page
- I see "Getting started with GitLab"
- The first step is the prerequisites which points to
installation/tools.md
- Here I'm presented with kubectl and helm once again. The next steps section sends me back to the installation page
- Now, it's time to choose between the cloud providers
- After I set up my cluster, I'm pointed to the deploy docs
installation/deployment.md
- This page has much information and almost each section points to another document.
- command line options
- secrets
- storage
- TLS
- (Advanced) external postgres
- Redis/Redis HA
- (Advanced) external object storage
- Outgoing email (point to command line options) / SMTP (point to secrets)
- Incoming email (point to command line options) / SMTP (point to secrets)
- optional deploy CE (default EE)
- Actual deploy command
There's too many steps and many back and forths, so we should streamline the process.
Pages left as-is
-
advanced - stuff that can be used at installation time and later in the process. Maybe move under /installation
. Leave as-is for now. -
architecture - how the charts are architectured, for development purposes, but I can see it being useful for someone deciding to jump into the charts. Leave as-is for now. -
backup-restore - Leave as-is for now. Maybe create a management
dir and move it there in the future. -
charts - possibly rename this to sub-charts
? otherwise the ending URL will be https://docs.gitlab.com/charts/charts/. One other option is to make the root dir of the docs site/kubernetes
. Leave as-is for this iteration. -
releases - changelog of releases. How often is this updated? Can we deprecate this and transfer some info into another relevant page? Leave as-is for now. -
troubleshooting - Leave as-is.
Pages and links that moved location
-
cloud/ - Move to installation/
-
gitlab-qa/ - Move under development
-
helm - Move under installation/tools.md
-
kube-monkey - Move under development
-
minikube - Move under development
-
preparation/ - Move under development/
-
All links to yaml examples point to the full repository URLs.
Random thoughts
- Split to installation and management?
- In
/installation/deployment.html
under "Selecting configuration options" we guide the user to prepare a list of options that will then provide to thehelm install
command. Have on every section:- command to write down
- optional or not
Current tree structure
.
├── advanced
│ ├── external-db
│ │ ├── external-omnibus-psql.md
│ │ └── index.md
│ ├── external-gitaly
│ │ ├── external-omnibus-gitaly.md
│ │ └── index.md
│ ├── external-nginx
│ │ └── index.md
│ ├── external-object-storage
│ │ └── index.md
│ ├── external-redis
│ │ ├── external-omnibus-redis.md
│ │ └── index.md
│ ├── index.md
│ └── persistent-volumes
│ └── index.md
├── architecture
│ ├── architecture.md
│ ├── backup-restore.md
│ ├── decisions.md
│ ├── goals.md
│ ├── index.md
│ └── resource-usage.md
├── backup-restore
│ ├── backup.md
│ ├── index.md
│ └── restore.md
├── charts
│ ├── gitlab
│ │ ├── gitaly
│ │ ├── gitlab-runner
│ │ ├── gitlab-shell
│ │ ├── index.md
│ │ ├── migrations
│ │ ├── sidekiq
│ │ └── unicorn
│ ├── globals.md
│ ├── index.md
│ ├── minio
│ │ └── index.md
│ ├── nginx
│ │ └── index.md
│ ├── redis
│ │ └── index.md
│ ├── redis-ha
│ │ └── index.md
│ ├── registry
│ │ └── index.md
│ └── shared-secrets
│ └── index.md
├── cloud
│ ├── eks.md
│ ├── gke.md
│ ├── index.md
│ └── openshift.md
├── development
│ ├── changelog-manager.md
│ ├── changelog.md
│ ├── deprecations.md
│ ├── index.md
│ └── release.md
├── example-config.yaml
├── gitlab-qa
│ └── index.md
├── helm
│ ├── examples
│ │ └── rbac-config.yaml
│ └── index.md
├── images
│ └── charts.png
├── index.md
├── installation
│ ├── command-line-options.md
│ ├── deployment.md
│ ├── index.md
│ ├── migration
│ │ ├── index.md
│ │ └── minio.md
│ ├── operator.md
│ ├── rbac.md
│ ├── secrets.md
│ ├── storage.md
│ ├── tls.md
│ ├── tools.md
│ ├── upgrade.md
│ └── version-mappings.md
├── kube-monkey
│ └── index.md
├── minikube
│ └── index.md
├── preparation
│ └── index.md
├── releases
│ ├── 1_0.md
│ ├── alpha.md
│ ├── beta.md
│ └── index.md
└── troubleshooting
└── index.md
36 directories, 64 files
Edited by Achilleas Pipinellis