blob: c199366f4fa28fffd863d5e2587c1d78e782af9a (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
|
---
stage: none
group: unassigned
info: 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](../../../user/feature_flags.md) | [Generated during docs build](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/doc/raketasks.md#generate-the-feature-flag-tables) | [Technical Writing](https://about.gitlab.com/handbook/product/ux/technical-writing/) |
| [GitLab Runner feature flags](https://docs.gitlab.com/runner/configuration/feature-flags.html) | [Page source](https://gitlab.com/gitlab-org/gitlab-runner/-/blob/ec6e1797d2173a95c8ac7f726bd62f6f110b7211/docs/configuration/feature-flags.md?plain=1#L39) | [Runner](https://about.gitlab.com/handbook/engineering/development/ops/verify/runner/) |
| [Deprecations and removals by version](../../../update/deprecations.md) | [Deprecating GitLab features](../../deprecation_guidelines/index.md) | |
| [GraphQL API resources](../../../api/graphql/reference/index.md) | [GraphQL API style guide](../../api_graphql_styleguide.md#documentation-and-schema) | [Import and Integrate](https://about.gitlab.com/handbook/engineering/development/dev/manage/import-and-integrate/) |
| [Audit event types](../../../administration/audit_event_streaming/audit_event_types.md) | [Audit event development guidelines](../../audit_event_guide/index.md) | [Compliance](https://about.gitlab.com/handbook/engineering/development/sec/govern/compliance/) |
| DAST vulnerability check documentation ([Example](../../../user/application_security/dast/checks/798.19.md)) | [How to generate the Markdown](https://gitlab.com/gitlab-org/security-products/dast-cwe-checks/-/blob/main/doc/how-to-generate-the-markdown-documentation.md) | [Dynamic Analysis](https://about.gitlab.com/handbook/product/categories/#dynamic-analysis-group) |
| Blueprints ([Example](../../../architecture/blueprints/ci_data_decay/pipeline_partitioning.md)) | | |
| [The docs homepage](../../../index.md) | | [Technical Writing](https://about.gitlab.com/handbook/product/ux/technical-writing/) |
## Make an automation request
If you want to automate a page on the docs site:
1. Review [issue 823](https://gitlab.com/gitlab-org/gitlab-docs/-/issues/823)
and consider adding feedback there.
1. If that issue does not describe what you need, contact
[the DRI for the docs site backend](https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects).
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.
|
