Skip to content

Add the GET documentation to docs.gitlab.com

Problem Statement

What is the problem?

We've got great Docs for using GET, but they are not available on docs.gitlab.com.

Documentation is the single source of truth for our customers, colleagues, and community.

Why is this a problem?

Keeping portions of documentation separate from our official documentation creates multiple sources of truth.

Proposal

Migrate the documentation in gitlab-environment-toolkit/docs to gitlab/doc/administration/reference_architectures or somewhere in gitlab-org/gitlab/doc/administration.

Implementation

Phase 1: Planning & Structure

  • Define navigation placement
  • Create content structure plan (CTRT)

Phase 2: Content Preparation

  • Change filenames (drop environment_ prefix)
  • Rename README.md → _index.md
  • Add YAML metadata to all pages
  • Change titles/descriptions
  • Enforce Vale rules
  • Link to full repository URLs
  • Optional: Convert PlantUML → Mermaid

Phase 3: Integration

  • Strip down README, cross-link to docs
  • Change DOCS_BRANCH to main in .gitlab/ci/docs.yml
  • Add cross-links from RA pages
  • Update installation method docs

Phase 4: Validation & Launch

Edited by Achilleas Pipinellis
To upload designs, you'll need to enable LFS and have an admin enable hashed storage. More information