diff options
Diffstat (limited to 'doc/development/documentation/styleguide')
| -rw-r--r-- | doc/development/documentation/styleguide/index.md | 144 | ||||
| -rw-r--r-- | doc/development/documentation/styleguide/word_list.md | 170 |
2 files changed, 187 insertions, 127 deletions
diff --git a/doc/development/documentation/styleguide/index.md b/doc/development/documentation/styleguide/index.md index 7787366dbf4..a5345f3b52d 100644 --- a/doc/development/documentation/styleguide/index.md +++ b/doc/development/documentation/styleguide/index.md @@ -193,7 +193,7 @@ included in backticks. For example: We include concept and task topic types in the same larger topic. -In general, we have one topic that's a [landing page](../structure.md#landing-pages). +In general, we have one topic that's a landing page. Below that topic in the left nav are individual topics. Each of these include a concept and multiple related tasks, reference, and troubleshooting topics. @@ -304,7 +304,6 @@ GitLab documentation should be clear and easy to understand. Avoid unnecessary w - Be clear, concise, and stick to the goal of the topic. - Write in US English with US grammar. (Tested in [`British.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/British.yml).) -- Use [inclusive language](#inclusive-language). - Rewrite to avoid wordiness: - there is - there are @@ -385,80 +384,6 @@ references to user interface elements. For example: - To sign in to product X, enter your credentials, and then select **Log in**. -### Inclusive language - -We strive to create documentation that's inclusive. This section includes -guidance and examples for these categories: - -- [Gender-specific wording](#avoid-gender-specific-wording). - (Tested in [`InclusionGender.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionGender.yml).) -- [Ableist language](#avoid-ableist-language). - (Tested in [`InclusionAbleism.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionAbleism.yml).) -- [Cultural sensitivity](#culturally-sensitive-language). - (Tested in [`InclusionCultural.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionCultural.yml).) - -We write our developer documentation with inclusivity and diversity in mind. This -page is not an exhaustive reference, but describes some general guidelines and -examples that illustrate some best practices to follow. - -#### Avoid gender-specific wording - -When possible, use gender-neutral pronouns. For example, you can use a singular -[they](https://developers.google.com/style/pronouns#gender-neutral-pronouns) as -a gender-neutral pronoun. - -Avoid the use of gender-specific pronouns, unless referring to a specific person. - -<!-- vale gitlab.InclusionGender = NO --> - -| Use | Avoid | -|-----------------------------------|---------------------------------| -| People, humanity | Mankind | -| GitLab Team Members | Manpower | -| You can install; They can install | He can install; She can install | - -<!-- vale gitlab.InclusionGender = YES --> - -If you need to set up [Fake user information](#fake-user-information), use -diverse or non-gendered names with common surnames. - -#### Avoid ableist language - -Avoid terms that are also used in negative stereotypes for different groups. - -<!-- vale gitlab.InclusionAbleism = NO --> - -| Use | Avoid | -|------------------------|----------------------| -| Check for completeness | Sanity check | -| Uncertain outliers | Crazy outliers | -| Slows the service | Cripples the service | -| Placeholder variable | Dummy variable | -| Active/Inactive | Enabled/Disabled | -| On/Off | Enabled/Disabled | - -<!-- vale gitlab.InclusionAbleism = YES --> - -Credit: [Avoid ableist language](https://developers.google.com/style/inclusive-documentation#ableist-language) -in the Google Developer Style Guide. - -#### Culturally sensitive language - -Avoid terms that reflect negative cultural stereotypes and history. In most -cases, you can replace terms such as `master` and `slave` with terms that are -more precise and functional, such as `primary` and `secondary`. - -<!-- vale gitlab.InclusionCultural = NO --> - -| Use | Avoid | -|----------------------|-----------------------| -| Primary / secondary | Master / slave | -| Allowlist / denylist | Blacklist / whitelist | - -<!-- vale gitlab.InclusionCultural = YES --> - -For more information see the [Internet Draft specification](https://tools.ietf.org/html/draft-knodel-terminology-02). - ### Fake user information You may need to include user information in entries such as a REST call or user profile. @@ -574,7 +499,7 @@ Follow these guidelines for punctuation: | Do not use tabs for indentation. Use spaces instead. You can configure your code editor to output spaces instead of tabs when pressing the tab key. | --- | | Use serial commas (_Oxford commas_) before the final _and_ or _or_ in a list of three or more items. (Tested in [`OxfordComma.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/OxfordComma.yml).) | _You can create new issues, merge requests, and milestones._ | | Always add a space before and after dashes when using it in a sentence (for replacing a comma, for example). | _You should try this - or not._ | -| Always use lowercase after a colon. | Linked issues: a way to create a relationship between issues._ | +| When a colon is part of a sentence, always use lowercase after the colon. | _Linked issues: a way to create a relationship between issues._ | <!-- vale gitlab.Repetition = YES --> @@ -812,6 +737,35 @@ page), use these phrases: | No | `**{dotted-circle}** No` | **{dotted-circle}** No | | Yes | `**{check-circle}** Yes` | **{check-circle}** Yes | +### Footnotes + +To indicate a footnote, use the HTML tag `<sup>` with a number. +Put the tag at the end of the sentence or term. + +For the footnotes below the table, use a bold number followed by a sentence. + +For example: + +```markdown +| App name | Description | +|:---------|:---------------------------------| +| App A | Description text. <sup>1</sup> | +| App B | Description text. <sup>2</sup> | + +1. This is the footnote. +1. This is the other footnote. +``` + +This text renders this output: + +| App name | Description | +|:---------|:---------------------------------| +| App A | Description text. <sup>1</sup> | +| App B | Description text. <sup>2</sup> | + +1. This is the footnote. +1. This is the other footnote. + ## Quotes Valid for Markdown content only, not for front matter entries: @@ -1093,21 +1047,23 @@ elements: To be consistent, use this format when you write about UI navigation. -1. On the top bar, select **Menu > Project** and find your project. +1. On the top bar, select **Menu > Projects** and find your project. 1. On the left sidebar, select **Settings > CI/CD**. 1. Expand **General pipelines**. Another example: -1. On the top bar, select **Menu > Group** and find your group. +1. On the top bar, select **Menu > Groups** and find your group. 1. On the left sidebar, select **Settings > CI/CD**. 1. Expand **General pipelines**. An Admin Area example: -`1. On the top bar, select **Menu >** **{admin}** **Admin**.` +```markdown +1. On the top bar, select **Menu >** **{admin}** **Admin**. +``` -This text generates this HTML: +This text renders this output: 1. On the top bar, select **Menu >** **{admin}** **Admin**. @@ -1510,25 +1466,6 @@ It renders on the GitLab documentation site as: To maintain consistency through GitLab documentation, use these styles and terms. -### Merge requests (MRs) - -Merge requests allow you to exchange changes you made to source code and -collaborate with other people on the same project. - -- Use lowercase _merge requests_ regardless of whether referring to the feature - or individual merge requests. - -As noted in the GitLab [Writing Style Guidelines](https://about.gitlab.com/handbook/communication/#writing-style-guidelines), -if you use the _MR_ acronym, expand it at least once per document page. -Typically, the first use would be phrased as _merge request (MR)_ with subsequent -instances being _MR_. - -Examples: - -- "We prefer GitLab merge requests". -- "Open a merge request to fix a broken link". -- "After you open a merge request (MR), submit your MR for review and approval". - ### Describe UI elements Follow these styles when you're describing user interface elements in an @@ -1558,7 +1495,7 @@ elements: ## GitLab versions -GitLab product documentation pages (not including [Contributor and Development](../../README.md) +GitLab product documentation pages (not including [Contributor and Development](../../index.md) pages in the `/development` directory) can include version information to help users be aware of recent improvements or additions. @@ -1594,7 +1531,8 @@ the section. The version information must: - Be surrounded by blank lines. - Start with `>`. If there are multiple bullets, each line must start with `> -`. - The string must include these words in this order (capitalization doesn't matter): - - `introduced`, `deprecated`, `moved` + - `introduced`, `deprecated`, `changed`, `moved`, `recommended` (as in the + [feature flag documentation](../feature_flags.md)), `removed`, or `renamed` - `in` or `to` - `GitLab` - Whenever possible, include a link to the completed issue, merge request, or epic @@ -1757,7 +1695,7 @@ badges and tooltips (`<span class="badge-trigger free">`). | _Only_ GitLab Ultimate SaaS (no self-managed instances) | `**(ULTIMATE SAAS)**` | Topics that mention the `gitlab.rb` file are referring to -self-managed instances of GitLab. To prevent confusion, include the relevant `TIER ONLY` +self-managed instances of GitLab. To prevent confusion, include the relevant `TIER SELF` tier badge on the highest applicable heading level on the page. diff --git a/doc/development/documentation/styleguide/word_list.md b/doc/development/documentation/styleguide/word_list.md index fd8766bbfb6..3fba9078bab 100644 --- a/doc/development/documentation/styleguide/word_list.md +++ b/doc/development/documentation/styleguide/word_list.md @@ -9,6 +9,11 @@ description: 'Writing styles, markup, formatting, and other standards for GitLab To help ensure consistency in the documentation, follow this guidance. +For guidance not on this page, we defer to these style guides: + +- [Microsoft Style Guide](https://docs.microsoft.com/en-us/style-guide/welcome/) +- [Google Developer Documentation Style Guide](https://developers.google.com/style) + <!-- vale off --> <!-- markdownlint-disable --> @@ -22,7 +27,13 @@ Use **administration**, **administrator**, **administer**, or **Admin Area** ins ## allow, enable -Try to avoid, unless you are talking about security-related features. For example, instead of "This feature allows you to create a pipeline," use "Use this feature to create a pipeline." This phrasing is more active and is from the user perspective, rather than the person who implemented the feature. [View details](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/a/allow-allows). +Try to avoid, unless you are talking about security-related features. For example: + +- Avoid: This feature allows you to create a pipeline. +- Use instead: Use this feature to create a pipeline. + +This phrasing is more active and is from the user perspective, rather than the person who implemented the feature. +[View details in the Microsoft style guide](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/a/allow-allows). ## and/or @@ -32,25 +43,49 @@ Instead of **and/or**, use or or rewrite the sentence to spell out both options. Try to avoid extra words when referring to an example or table in a documentation page, but if required, use **following** instead. +## blacklist + +Do not use. Another option is **denylist**. ([Vale](../testing.md#vale) rule: [`InclusionCultural.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionCultural.yml)) + ## currently Do not use when talking about the product or its features. The documentation describes the product as it is today. ([Vale](../testing.md#vale) rule: [`CurrentStatus.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/CurrentStatus.yml)) ## Developer -When writing about the Developer role, use a capital "D." Do not use the phrase, "if you are a developer" -to mean someone who is assigned the Developer role. Instead, write it out. "If you are assigned the Developer role..." +When writing about the Developer role: -Do not use "Developer permissions." A user who is assigned the Developer role has a set of associated permissions. +- Use a capital **D**. +- Do not use the phrase, **if you are a developer** to mean someone who is assigned the Developer + role. Instead, write it out. For example, **if you are assigned the Developer role**. +- To describe a situation where the Developer role is the minimum required: + - Avoid: **the Developer role or higher** + - Use instead: **at least the Developer role** + +Do not use **Developer permissions**. A user who is assigned the Developer role has a set of associated permissions. + +## disable + +See [the Microsoft style guide](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/d/disable-disabled) for guidance. +Use **inactive** or **off** instead. ([Vale](../testing.md#vale) rule: [`InclusionAbleism.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionAbleism.yml)) ## easily -Do not use. If the user doesn't find the process to be these things, we lose their trust. +Do not use. If the user doesn't find the process to be easy, we lose their trust. ## e.g. Do not use Latin abbreviations. Use **for example**, **such as**, **for instance**, or **like** instead. ([Vale](../testing.md#vale) rule: [`LatinTerms.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/LatinTerms.yml)) +## email + +Do not use **e-mail** with a hyphen. When plural, use **emails** or **email messages**. + +## enable + +See [the Microsoft style guide](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/e/enable-enables) for guidance. +Use **active** or **on** instead. ([Vale](../testing.md#vale) rule: [`InclusionAbleism.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionAbleism.yml)) + ## future tense When possible, use present tense instead. For example, use `after you execute this command, GitLab displays the result` instead of `after you execute this command, GitLab will display the result`. ([Vale](../testing.md#vale) rule: [`FutureTense.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/FutureTense.yml)) @@ -59,16 +94,35 @@ When possible, use present tense instead. For example, use `after you execute th Do not make possessive (GitLab's). This guidance follows [GitLab Brand Guidelines](https://about.gitlab.com/handbook/marketing/corporate-marketing/brand-activation/brand-guidelines/#trademark). +### GitLab.com + +Refers to the GitLab instance managed by GitLab itself. + +### GitLab SaaS + +Refers to the product license that provides access to GitLab.com. Does not refer to the +GitLab instance managed by GitLab itself. + +### GitLab self-managed + +Refers to the product license for GitLab instances managed by customers themselves. + ## Guest -When writing about the Guest role, use a capital "G." Do not use the phrase, "if you are a guest" -to mean someone who is assigned the Guest role. Instead, write it out. "If you are assigned the Guest role..." +When writing about the Guest role: + +- Use a capital **G**. +- Do not use the phrase, **if you are a guest** to mean someone who is assigned the Guest + role. Instead, write it out. For example, **if you are assigned the Guest role**. +- To describe a situation where the Guest role is the minimum required: + - Avoid: **the Guest role or higher** + - Use instead: **at least the Guest role** -Do not use "Guest permissions." A user who is assigned the Guest role has a set of associated permissions. +Do not use **Guest permissions**. A user who is assigned the Guest role has a set of associated permissions. ## handy -Do not use. If the user doesn't find the process to be these things, we lose their trust. +Do not use. If the user doesn't find the feature or process to be handy, we lose their trust. ## high availability, HA @@ -84,10 +138,28 @@ Do not use Latin abbreviations. Use **that is** instead. ([Vale](../testing.md#v ## Maintainer -When writing about the Maintainer role, use a capital "M." Do not use the phrase, "if you are a maintainer" -to mean someone who is assigned the Maintainer role. Instead, write it out. "If you are assigned the Maintainer role..." +When writing about the Maintainer role: + +- Use a capital **M**. +- Do not use the phrase, **if you are a maintainer** to mean someone who is assigned the Maintainer + role. Instead, write it out. For example, **if you are assigned the Maintainer role**. +- To describe a situation where the Maintainer role is the minimum required: + - Avoid: **the Maintainer role or higher** + - Use instead: **at least the Maintainer role** + +Do not use **Maintainer permissions**. A user who is assigned the Maintainer role has a set of associated permissions. + +## mankind + +Do not use. Use **people** or **humanity** instead. ([Vale](../testing.md#vale) rule: [`InclusionGender.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionGender.yml)) -Do not use "Maintainer permissions." A user who is assigned the Maintainer role has a set of associated permissions. +## manpower + +Do not use. Use words like **workforce** or **GitLab team members**. ([Vale](../testing.md#vale) rule: [`InclusionGender.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionGender.yml)) + +## master + +Do not use. Options are **primary** or **main**. ([Vale](../testing.md#vale) rule: [`InclusionCultural.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionCultural.yml)) ## may, might @@ -97,12 +169,19 @@ Do not use "Maintainer permissions." A user who is assigned the Maintainer role Do not use first-person singular. Use **you**, **we**, or **us** instead. ([Vale](../testing.md#vale) rule: [`FirstPerson.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/FirstPerson.yml)) +## merge requests + +Lowercase. If you use **MR** as the acronym, spell it out on first use. + ## Owner -When writing about the Owner role, use a capital "M." Do not use the phrase, "if you are an owner" -to mean someone who is assigned the Owner role. Instead, write it out. "If you are assigned the Owner role..." +When writing about the Owner role: + +- Use a capital **O**. +- Do not use the phrase, **if you are an owner** to mean someone who is assigned the Owner + role. Instead, write it out. For example, **if you are assigned the Owner role**. -Do not use "Owner permissions." A user who is assigned the Owner role has a set of associated permissions. +Do not use **Owner permissions**. A user who is assigned the Owner role has a set of associated permissions. ## permissions @@ -118,38 +197,68 @@ Do not use. Doing so may negatively affect other users and contributors, which i ## Reporter -When writing about the Reporter role, use a capital "R." Do not use the phrase, "if you are a reporter" -to mean someone who is assigned the Reporter role. Instead, write it out. "If you are assigned the Reporter role..." +When writing about the Reporter role: -Do not use "Reporter permissions." A user who is assigned the Reporter role has a set of associated permissions. +- Use a capital **R**. +- Do not use the phrase, **if you are a reporter** to mean someone who is assigned the Reporter + role. Instead, write it out. For example, **if you are assigned the Reporter role**. +- To describe a situation where the Reporter role is the minimum required: + - Avoid: **the Reporter role or higher** + - Use instead: **at least the Reporter role** + +Do not use **Reporter permissions**. A user who is assigned the Reporter role has a set of associated permissions. ## roles Do not use roles and permissions interchangeably. Each user is assigned a role. Each role includes a set of permissions. +## sanity check + +Do not use. Use **check for completeness** instead. ([Vale](../testing.md#vale) rule: [`InclusionAbleism.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionAbleism.yml)) + ## scalability Do not use when talking about increasing GitLab performance for additional users. The words scale or scaling are sometimes acceptable, but references to increasing GitLab performance for additional users should direct readers to the GitLab [reference architectures](../../../administration/reference_architectures/index.md) page. -## simply +## setup, set up + +Use **setup** as a noun, and **set up** as a verb. For example: + +- Your remote office setup is amazing. +- To set up your remote office correctly, consider the ergonomics of your work area. + +## simply, simple -Do not use. If the user doesn't find the process to be these things, we lose their trust. +Do not use. If the user doesn't find the process to be simple, we lose their trust. ## slashes -Instead of **and/or**, use **or** or another sensible construction. This rule also applies to other slashes, like **follow/unfollow**. Some exceptions (like **CI/CD**) are allowed. +Instead of **and/or**, use **or** or re-write the sentence. This rule also applies to other slashes, like **follow/unfollow**. Some exceptions (like **CI/CD**) are allowed. + +## slave + +Do not use. Another option is **secondary**. ([Vale](../testing.md#vale) rule: [`InclusionCultural.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionCultural.yml)) ## subgroup -Use instead of `sub-group`. +Use instead of **sub-group**. ## that -Do not use. Example: `the file that you save` can be `the file you save`. +Do not use. For example: + +- Avoid: The file that you save... +- Use instead: The file you save... + +## they + +Avoid the use of gender-specific pronouns, unless referring to a specific person. +Use a singular [they](https://developers.google.com/style/pronouns#gender-neutral-pronouns) as +a gender-neutral pronoun. ## useful -Do not use. If the user doesn't find the process to be these things, we lose their trust. +Do not use. If the user doesn't find the process to be useful, we lose their trust. ## utilize @@ -159,5 +268,18 @@ Do not use. Use **use** instead. It's more succinct and easier for non-native En Do not use Latin abbreviations. Use **with**, **through**, or **by using** instead. ([Vale](../testing.md#vale) rule: [`LatinTerms.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/LatinTerms.yml)) +## we + +Try to avoid **we** and focus instead on how the user can accomplish something in GitLab. + +- Avoid: We created a feature for you to add widgets. +- Instead, use: Use widgets when you have work you want to organize. + +One exception: You can use **we recommend** instead of **it is recommended** or **GitLab recommends**. + +## whitelist + +Do not use. Another option is **allowlist**. ([Vale](../testing.md#vale) rule: [`InclusionCultural.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionCultural.yml)) + <!-- vale on --> <!-- markdownlint-enable --> |