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
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
|
---
info: For assistance with this Style Guide page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects.
stage: none
group: unassigned
---
# Metadata
Each documentation Markdown page contains YAML front matter.
All values in the metadata are treated as strings and are used for the
docs website only.
## Stage and group metadata
Each page should have metadata related to the stage and group it
belongs to, as well as an information block. For example:
```yaml
---
stage: Example Stage
group: Example Group
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments
---
```
To populate the metadata, include this information:
- `stage`: The [Stage](https://about.gitlab.com/handbook/product/categories/#devops-stages)
that the majority of the page's content belongs to.
- `group`: The [Group](https://about.gitlab.com/company/team/structure/#product-groups)
that the majority of the page's content belongs to.
- `info`: How to find the Technical Writer associated with the page's stage and
group.
### Exceptions
Documents in the `/development` directory get this metadata:
```yaml
---
stage: Example Stage
group: Example Group
info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review.
---
```
Documents in the `/solutions` directory get this metadata:
```yaml
---
stage: Solutions Architecture
group: Solutions Architecture
info: This page is owned by the Solutions Architecture team.
---
```
## Description metadata
The `description` tag:
- Is used to populate text on the docs home page.
- Is shown in social media previews.
- Can be used in search result snippets.
For the top-level pages, like **Use GitLab** and one level underneath,
the descriptions are lists of nouns. For example, for **Set up your organization**,
the description is `Users, groups, namespaces, SSH keys.`
For other pages, descriptions are not actively maintained. However, if you want to add one,
use a short description of what the page is about.
See the Google [Best practices for creating quality meta descriptions](https://developers.google.com/search/docs/appearance/snippet#meta-descriptions) for tips.
## Additional metadata
The following metadata is optional and is not actively maintained.
- `feedback`: Set to `false` to not include the "Help & Feedback" footer.
- `noindex`: Set to `false` to prevent the page from being indexed by search engines.
- `redirect_to`: Used to control redirects. For more information, see [Redirects in GitLab documentation](redirects.md).
- `searchbar`: Set to `false` to not include the search bar in the page header.
- `toc`: Set to `false` to not include the "On this page" navigation.
## Batch updates for TW metadata
The [`CODEOWNERS`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/CODEOWNERS)
file contains a list of files and the associated technical writers.
When a merge request contains documentation, the information in the `CODEOWNERS` file determines:
- The list of users in the **Approvers** section.
- The technical writer that the GitLab Bot pings for community contributions.
You can use a Rake task to update the `CODEOWNERS` file.
### Update the `CODEOWNERS` file
When groups or [TW assignments](https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments)
change, you must update the `CODEOWNERS` file:
1. Update the [stage and group metadata](#stage-and-group-metadata) for any affected doc pages, if necessary. If there are many changes, you can do this step in a separate MR.
1. Update the [`codeowners.rake`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/tasks/gitlab/tw/codeowners.rake) file with the changes.
1. Go to the root of the `gitlab` repository.
1. Run the Rake task with this command: `bundle exec rake tw:codeowners`
1. Review the changes in the `CODEOWNERS` file.
1. Add and commit all your changes and push your branch up to `origin`.
1. Create a merge request and assign it to a technical writing manager for review.
When you update the `codeowners.rake` file:
- To specify multiple writers for a single group, use a space between writer names. Files are assigned to both writers.
```ruby
CodeOwnerRule.new('Group Name', '@writer1 @writer2'),
```
- To assign different writers within a group to docs in different directories, use the `path` parameter to specify a directory:
```ruby
CodeOwnerRule.new('Group Name', ->(path) { path.start_with?('/doc/user') ? '@writer1' : '@writer2' }),
```
In this example, `writer1` is a code owner for files related to this group that are in `/doc/user`.
For everything else, `writer2` is made code owner. For an example, see [MR 127903](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/127903).
- For a group that does not have an assigned writer, include the group name in the file and comment out the line:
```ruby
# CodeOwnerRule.new('Group Name', ''),
```
|
