You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: doc/development/documentation/styleguide.md
+7-5Lines changed: 7 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -19,7 +19,7 @@ that apply to all GitLab content, not just documentation.
19
19
20
20
The documentation of GitLab products and features is the SSOT for all information related to implementation, usage, and troubleshooting. It evolves continually, in keeping with new products and features, and with improvements for clarity, accuracy, and completeness.
21
21
22
-
This policy prevents information silos, ensuring that it remains easy to find information about GitLab products.
22
+
This policy prevents information silos, making it easier to find information about GitLab products.
23
23
24
24
It also informs decisions about the kinds of content we include in our documentation.
25
25
@@ -61,7 +61,7 @@ Instead, link to the SSOT and explain why it is important to consume the informa
61
61
62
62
### Organize by topic, not by type
63
63
64
-
Beyond top-level audience-type folders (for example, `administration`), we organize content by topic, not by type, so that it can be located as easily as possible within the single-source-of-truth (SSOT) section for the subject matter.
64
+
Beyond top-level audience-type folders (for example, `administration`), we organize content by topic, not by type, so it can be located as easily as possible within the single-source-of-truth (SSOT) section for the subject matter.
65
65
66
66
For example, do not create groupings of similar media types. For example:
67
67
@@ -76,7 +76,7 @@ and cross-link between any related content.
76
76
77
77
### Docs-first methodology
78
78
79
-
We employ a **docs-first methodology** to help ensure that the docs remain a complete and trusted resource, and to make communicating about the use of GitLab more efficient.
79
+
We employ a **docs-first methodology** to help ensure the docs remain a complete and trusted resource, and to make communicating about the use of GitLab more efficient.
80
80
81
81
- If the answer to a question exists in documentation, share the link to the docs instead of rephrasing the information.
82
82
- When you encounter new information not available in GitLab’s documentation (for example, when working on a support case or testing a feature), your first step should be to create a merge request (MR) to add this information to the docs. You can then share the MR in order to communicate this information.
@@ -129,13 +129,13 @@ correctly, but is not the current standard for GitLab documentation).
129
129
A rule that could cause confusion is `MD044/proper-names`, as it might not be immediately
130
130
clear what caused markdownlint to fail, or how to correct the failure. This rule
131
131
checks a list of known words, listed in the `.markdownlint.json` file in each project,
132
-
to verify that proper capitalization and backticks are used. Words in backticks will
132
+
to verify proper use of capitalization and backticks. Words in backticks will
133
133
be ignored by markdownlint.
134
134
135
135
In general, product names should follow the exact capitalization of the official names
136
136
of the products, protocols, and so on.
137
137
138
-
Some examples that will fail if incorrect capitalization is used:
138
+
Some examples fail if incorrect capitalization is used:
139
139
140
140
- MinIO (needs capital `IO`)
141
141
- NGINX (needs all capitals)
@@ -252,6 +252,8 @@ GitLab documentation should be clear and easy to understand.
252
252
- Avoid uncommon words.
253
253
- Don't write in the first person singular.
254
254
- Instead of "I" or "me," use "we," "you," "us," or "one."
255
+
- When possible, stay user focused by writing in the second person ("you" or the imperative).
256
+
- Don't overuse "that". In many cases, you can remove "that" from a sentence and improve readability.
Copy file name to clipboardExpand all lines: doc/user/project/merge_requests/accessibility_testing.md
+4-1Lines changed: 4 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -46,9 +46,12 @@ Pa11y against the webpages defined in `a11y_urls`, and builds an HTML report for
46
46
47
47
The report for each URL is saved as an artifact that can be [viewed directly in your browser](../../../ci/pipelines/job_artifacts.md#browsing-artifacts).
48
48
49
-
A single `accessibility.json` artifact is created and saved along with the individual HTML reports.
49
+
A single `gl-accessibility.json` artifact is created and saved along with the individual HTML reports.
50
50
It includes report data for all URLs scanned.
51
51
52
+
NOTE: **Note:**
53
+
For GitLab 12.10 and earlier, the [artifact generated is named `accessibility.json`](https://gitlab.com/gitlab-org/ci-cd/accessibility/-/merge_requests/9).
54
+
52
55
NOTE: **Note:**
53
56
For GitLab versions earlier than 12.9, you can use `include:remote` and use a
54
57
link to the [current template in `master`](https://gitlab.com/gitlab-org/gitlab/-/raw/master/lib/gitlab/ci/templates/Verify/Accessibility.gitlab-ci.yml)
0 commit comments