Automated pages

Most pages in the GitLab documentation are written manually in Markdown. However, some pages are created by automated processes.

Two primary categories of automation exist in the GitLab documentation:

  • Content that is generated by using a standard process and structured data (for example, YAML or JSON files).
  • Content that is generated by any other means.

Automation helps with consistency and speed. But content that is automated in a non-standard way causes difficulty with:

  • Frontend changes.
  • Site troubleshooting and maintenance.
  • The contributor experience.

Ideally, any automation should be done in a standard way, which helps alleviate some of the downsides.

Pages generated from structured data

Some functionality on the docs site uses structured data:

  • Hierarchical global navigation (YAML)
  • Survey banner (YAML)
  • Badges (YAML)
  • Homepage content lists (YAML)
  • Redirects (YAML)
  • Versions menu (JSON)

Pages generated otherwise

Other pages are generated by using non-standard processes. These pages often use solutions that are coded across multiple repositories.

PageDetailsOwner
All feature flags in GitLabGenerated during docs buildTechnical Writing
GitLab Runner feature flagsPage sourceRunner
GitLab Runner Kubernetes API settingsGenerated with mageRunner
Deprecations and removals by versionUpdate the deprecations and removals documentation
Breaking change windowsUpdate the breaking change windows documentation
GraphQL API resourcesGraphQL API style guideImport and Integrate
Audit event typesAudit event development guidelinesCompliance
Available custom role permissionsGenerated by Rake taskAuthorization
CI/CD Job token fine-grained permissionsGenerated by Rake taskAuthorization
Application settings analysisGenerated by Ruby script
DAST vulnerability check documentation (Example)How to generate the MarkdownDynamic Analysis
The docs homepageTechnical Writing

Make an automation request

If you want to automate a page on the docs site:

  1. Review issue 246 and consider adding feedback there.
  2. If that issue does not describe what you need, contact the DRI for the docs site backend.

Because automation adds extra complexity and a support burden, we review it on a case-by-case basis.

Document the automation

If you do add automation, you must document:

  • The list of files that are included.
  • The .gitlab-ci.yml updates and any pipeline requirements.
  • The steps needed to troubleshoot.

Other GitLab team members should be able to easily find information about how to maintain the automation. You should announce the change widely, including, at a minimum:

  • In Slack, in #whats-happening-at-gitlab.
  • In the Technical Writer team meeting agenda.