diff options
Diffstat (limited to 'doc/development/documentation/styleguide')
| -rw-r--r-- | doc/development/documentation/styleguide/index.md | 102 | ||||
| -rw-r--r-- | doc/development/documentation/styleguide/word_list.md | 32 |
2 files changed, 89 insertions, 45 deletions
diff --git a/doc/development/documentation/styleguide/index.md b/doc/development/documentation/styleguide/index.md index 7f2e5a1ba26..e57ffb90028 100644 --- a/doc/development/documentation/styleguide/index.md +++ b/doc/development/documentation/styleguide/index.md @@ -1,5 +1,7 @@ --- info: For assistance with this Style Guide page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-other-projects-and-subjects. +stage: none +group: unassigned description: 'Writing styles, markup, formatting, and other standards for GitLab Documentation.' --- @@ -13,7 +15,7 @@ use the `#docs-processes` channel. In addition to this page, the following resources can help you craft and contribute to documentation: - [Doc contribution guidelines](../index.md) -- [A-Z word list](word_list.md) +- [Recommended word list](word_list.md) - [Doc style and consistency testing](../testing.md) - [UI text guidelines](https://design.gitlab.com/content/error-messages/) - [GitLab Handbook style guidelines](https://about.gitlab.com/handbook/communication/#writing-style-guidelines) @@ -392,39 +394,26 @@ especially in tutorials, instructional documentation, and Some contractions, however, should be avoided: -- Do not use the word "GitLab" in a contraction. +<!-- vale gitlab.Possessive = NO --> -- Do not use contractions with a proper noun and a verb. For example: +| Do not use a contraction | Example | Use instead | +|-------------------------------|--------------------------------------------------|------------------------------------------------------------------| +| With a proper noun and a verb | The **Container Registry's** a powerful feature. | The **Container Registry** is a powerful feature. | +| To emphasize a negative | **Don't** install X with Y. | **Do not** install X with Y. | +| In reference documentation | **Don't** set a limit. | **Do not** set a limit. | +| In error messages | Requests to localhost **aren't** allowed. | Requests to localhost **are not** allowed. | - | Do | Don't | - |------------------------------------------|-----------------------------------------| - | Canada is establishing X. | Canada's establishing X. | - -- Do not use contractions when you need to emphasize a negative. For example: - - | Do | Don't | - |------------------------------------------|-----------------------------------------| - | Do not install X with Y. | Don't install X with Y. | - -- Do not use contractions in reference documentation. For example: - - | Do | Don't | - |------------------------------------------|-----------------------------------------| - | Do not set a limit greater than 1000. | Don't set a limit greater than 1000. | - | For `parameter1`, the default is 10. | For `parameter1`, the default's 10. | - -- Avoid contractions in error messages. Examples: - - | Do | Don't | - |------------------------------------------|-----------------------------------------| - | Requests to localhost are not allowed. | Requests to localhost aren't allowed. | - | Specified URL cannot be used. | Specified URL can't be used. | +<!-- vale gitlab.Possessive = YES --> ### Acronyms If you use an acronym, spell it out on first use on a page. You do not need to spell it out more than once on a page. When possible, try to avoid acronyms in headings. +### Numbers + +When using numbers in text, spell out zero through nine, and use numbers for 10 and greater. For details, see the [Microsoft Style Guide](https://docs.microsoft.com/en-us/style-guide/numbers). + ## Text - [Write in Markdown](#markdown). @@ -1626,7 +1615,7 @@ 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`, `changed`, `moved`, `recommended` (as in the + - `introduced`, `enabled`, `deprecated`, `changed`, `moved`, `recommended` (as in the [feature flag documentation](../feature_flags.md)), `removed`, or `renamed` - `in` or `to` - `GitLab` @@ -1667,24 +1656,6 @@ If a feature is moved to another tier: > - [Moved](<link-to-issue>) from GitLab Premium to GitLab Free in 12.0. ``` -If a feature is deprecated, include a link to a replacement (when available): - -```markdown -> - [Deprecated](<link-to-issue>) in GitLab 11.3. Replaced by [meaningful text](<link-to-appropriate-documentation>). -``` - -You can also describe the replacement in surrounding text, if available. If the -deprecation isn't obvious in existing text, you may want to include a warning: - -```markdown -WARNING: -This feature was [deprecated](link-to-issue) in GitLab 12.3 and replaced by -[Feature name](link-to-feature-documentation). -``` - -In the first major GitLab version after the feature was deprecated, be sure to -remove information about that deprecated feature. - #### Inline version text If you're adding content to an existing topic, you can add version information @@ -1784,6 +1755,47 @@ To view historical information about a feature, review GitLab [release posts](https://about.gitlab.com/releases/), or search for the issue or merge request where the work was done. +### Deprecated features + +When a feature is deprecated, add `(DEPRECATED)` to the page title or to +the heading of the section documenting the feature, immediately before +the tier badge: + +```markdown +<!-- Page title example: --> +# Feature A (DEPRECATED) **(ALL TIERS)** + +<!-- Doc section example: --> +## Feature B (DEPRECATED) **(PREMIUM SELF)** +``` + +Add the deprecation to the version history note (you can include a link +to a replacement when available): + +```markdown +> - [Deprecated](<link-to-issue>) in GitLab 11.3. Replaced by [meaningful text](<link-to-appropriate-documentation>). +``` + +You can also describe the replacement in surrounding text, if available. If the +deprecation isn't obvious in existing text, you may want to include a warning: + +```markdown +WARNING: +This feature was [deprecated](link-to-issue) in GitLab 12.3 and replaced by +[Feature name](link-to-feature-documentation). +``` + +If you add `(DEPRECATED)` to the page's title and the document is linked from the docs +navigation, either remove the page from the nav or update the nav item to include the +same text before the feature name: + +```yaml + - doc_title: (DEPRECATED) Feature A +``` + +In the first major GitLab version after the feature was deprecated, be sure to +remove information about that deprecated feature. + ## Products and features Refer to the information in this section when describing products and features diff --git a/doc/development/documentation/styleguide/word_list.md b/doc/development/documentation/styleguide/word_list.md index 9c375379685..dc3dcba0c95 100644 --- a/doc/development/documentation/styleguide/word_list.md +++ b/doc/development/documentation/styleguide/word_list.md @@ -25,6 +25,13 @@ Try to avoid **`@mention`**. Say **mention** instead, and consider linking to th [mentions topic](../../../user/discussions/index.md#mentions). Don't use backticks. +## 2FA, two-factor authentication + +Spell out **two-factor authentication** in sentence case for the first use and in section headings, and **2FA** +thereafter. If the first word in a sentence, do not capitalize `factor` or `authentication`. For example: + +- Two-factor authentication (2FA) helps secure your account. Set up 2FA when you first log in. + ## above Try to avoid using **above** when referring to an example or table in a documentation page. If required, use **previous** instead. For example: @@ -182,6 +189,11 @@ Use **check out** as a verb. For the Git command, use `checkout`. CI/CD is always uppercase. No need to spell it out on first use. +## CI/CD minutes + +Use **CI/CD minutes** instead of **CI minutes**, **pipeline minutes**, **pipeline minutes quota**, or +**CI pipeline minutes**. This decision was made in [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/342813). + ## click Do not use **click**. Instead, use **select** with buttons, links, menu items, and lists. @@ -197,11 +209,19 @@ Use **confirmation dialog** to describe the dialog box that asks you to confirm - On the confirmation dialog, select **OK**. +## Container Registry + +Use title case for the GitLab Container Registry. + ## currently Do not use **currently** 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)) +## Dependency Proxy + +Use title case for the GitLab Dependency Proxy. + ## deploy board Use lowercase for **deploy board**. @@ -614,6 +634,10 @@ When writing about the Owner role: Do not use **Owner permissions**. A user who is assigned the Owner role has a set of associated permissions. +## Package Registry + +Use title case for the GitLab Package Registry. + ## permissions Do not use [**roles**](#roles) and **permissions** interchangeably. Each user is assigned a role. Each role includes a set of permissions. @@ -634,6 +658,10 @@ Use **press** when talking about keyboard keys. For example: Do not use profanity. Doing so may negatively affect other users and contributors, which is contrary to the GitLab value of [Diversity, Inclusion, and Belonging](https://about.gitlab.com/handbook/values/#diversity-inclusion). +## push rules + +Use lowercase for **push rules**. + ## Reporter When writing about the Reporter role: @@ -825,6 +853,10 @@ You **turn on** or **turn off** a toggle. For example: - Turn on the **blah** toggle. +## TFA, two-factor authentication + +Use [**2FA** and **two-factor authentication**](#2fa-two-factor-authentication) instead. + ## type Do not use **type** if you can avoid it. Use **enter** instead. |