gitlab-foss/doc/development/documentation/site_architecture/automation.md

stage, group, info, title

stage	group	info	title
none	unassigned	For assistance with this Style Guide page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects.	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.

Page	Details	Owner
All feature flags in GitLab	Generated during docs build	Technical Writing
GitLab Runner feature flags	Page source	Runner
GitLab Runner Kubernetes API settings	Generated with mage	Runner
Deprecations and removals by version	Update the deprecations and removals documentation
Breaking change windows	Update the breaking change windows documentation
GraphQL API resources	GraphQL API style guide	Import and Integrate
REST API OpenAPI V2 documentation	Documenting REST API resources	Import and Integrate
Audit event types	Audit event development guidelines	Compliance
Available custom role permissions	Generated by Rake task	Authorization
CI/CD Job token fine-grained permissions	Generated by Rake task	Authorization
Application settings analysis	Generated by Ruby script
DAST vulnerability check documentation (Example)	How to generate the Markdown	Dynamic Analysis
The docs homepage		Technical 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.