diff options
Diffstat (limited to 'doc/development/documentation/styleguide')
| -rw-r--r-- | doc/development/documentation/styleguide/index.md | 113 | ||||
| -rw-r--r-- | doc/development/documentation/styleguide/word_list.md | 122 |
2 files changed, 181 insertions, 54 deletions
diff --git a/doc/development/documentation/styleguide/index.md b/doc/development/documentation/styleguide/index.md index d629bc0b87e..ef934186981 100644 --- a/doc/development/documentation/styleguide/index.md +++ b/doc/development/documentation/styleguide/index.md @@ -18,11 +18,22 @@ In addition to this page, the following resources can help you craft and contrib - [Recommended word list](word_list.md) - [Doc style and consistency testing](../testing.md) - [Guidelines for UI error messages](https://design.gitlab.com/content/error-messages/) +- [Documentation global navigation](../site_architecture/global_nav.md) - [GitLab Handbook style guidelines](https://about.gitlab.com/handbook/communication/#writing-style-guidelines) - [Microsoft Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/) - [Google Developer Documentation Style Guide](https://developers.google.com/style) - [Recent updates to this guide](https://gitlab.com/dashboard/merge_requests?scope=all&state=merged&label_name[]=tw-style¬[label_name][]=docs%3A%3Afix) +## The GitLab voice + +The GitLab brand guidelines define the +[voice used by the larger organization](https://design.gitlab.com/brand/overview/#tone-of-voice). + +Building on that guidance, the voice in the GitLab documentation strives to be concise, +direct, and precise. The goal is to provide information that's easy to search and scan. + +The voice in the documentation should be conversational but brief, friendly but succinct. + ## Documentation is the single source of truth (SSOT) The GitLab documentation is the SSOT for all @@ -125,6 +136,23 @@ Maintaining a knowledge base separate from the documentation would be against the documentation-first methodology, because the content would overlap with the documentation. +## Writing for localization + +The GitLab documentation is not localized, but we follow guidelines that +help benefit translation. For example, we: + +- Write in [active voice](word_list.md#active-voice). +- Write in [present tense](word_list.md#future-tense). +- Avoid words that can be translated incorrectly, like: + - [since and because](word_list.md#since) + - [once and after](word_list.md#once) + - [it](word_list.md#it) +- Avoid [ing](word_list.md#-ing-words) words. + +[The GitLab voice](#the-gitlab-voice) dictates that we write clearly and directly, +and with translation in mind. [The word list](word_list.md) and our Vale rules +also aid in consistency, which is important for localization. + ## Markdown All GitLab documentation is written using [Markdown](https://en.wikipedia.org/wiki/Markdown). @@ -143,26 +171,17 @@ Hard-coded HTML is valid, although it's discouraged from being used. HTML is per - Special styling is required. - Reviewed and approved by a technical writer. -### Headings in Markdown +### Heading levels in Markdown Each documentation page begins with a level 1 heading (`#`). This becomes the `h1` element when the page is rendered to HTML. There can be only **one** level 1 heading per page. - For each subsection, increment the heading level. In other words, increment the number of `#` characters - in front of the heading. -- Avoid headings greater than `H5` (`#####`). If you need more than five heading levels, move the topics to a new page instead. - Headings greater than `H5` do not display in the right sidebar navigation. + in front of the topic title. +- Avoid heading levels greater than `H5` (`#####`). If you need more than five heading levels, move the topics to a new page instead. + Heading levels greater than `H5` do not display in the right sidebar navigation. - Do not skip a level. For example: `##` > `####`. -- Leave one blank line before and after the heading. - -When you change heading text, the anchor link changes. To avoid broken links: - -- Do not use step numbers in headings. -- When possible, do not use words that might change in the future. - -Also, do not use links as part of heading text. - -See also [heading guidelines for specific topic types](../structure.md). +- Leave one blank line before and after the topic title. ### Backticks in Markdown @@ -221,9 +240,9 @@ GitLab documentation should be clear and easy to understand. As a company, we tend toward lowercase. -#### Headings +#### Topic titles -Use sentence case. For example: +Use sentence case for topic titles. For example: - `# Use variables to configure pipelines` - `## Use the To-Do List` @@ -329,7 +348,7 @@ Some contractions, however, should be avoided: ### 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. +When possible, try to avoid acronyms in topic titles. ### Numbers @@ -374,22 +393,31 @@ You can use italics when you are introducing a term for the first time. Otherwis ### Punctuation -Follow these guidelines for punctuation: +Follow these guidelines for punctuation. <!-- vale gitlab.Repetition = NO --> - End full sentences with a period. -- Use one space between sentences. -- Do not use semicolons. Use two sentences instead. -- Do not use double spaces. (Tested in [`SentenceSpacing.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/SentenceSpacing.yml).) -- Do not use non-breaking spaces. Use standard spaces instead. (Tested in [`lint-doc.sh`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/scripts/lint-doc.sh).) -- 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 (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).) -- Avoid dashes. Use separate sentences, or commas, instead. -- Do not use typographer's ("curly") quotes. Use straight quotes instead. (Tested in [`NonStandardQuotes.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/NonStandardQuotes.yml).) <!-- vale gitlab.Repetition = YES --> +When spacing content: + +- Use one space between sentences. (Use of more than one space is tested in [`SentenceSpacing.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/SentenceSpacing.yml).) +- Do not use non-breaking spaces. Use standard spaces instead. (Tested in [`lint-doc.sh`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/scripts/lint-doc.sh).) +- Do not use tabs for indentation. Use spaces instead. You can configure your code editor to output spaces instead of tabs when pressing the <kbd>Tab</kbd> key. + +<!-- vale gitlab.NonStandardQuotes = NO --> + +Do not use these punctuation characters: + +- `;` (semicolon): Use two sentences instead. +- `–` (en dash) or `—` (em dash): Use separate sentences, or commas, instead. +- `“` `”` `‘` `’`: Double or single typographer's ("curly") quotation marks. Use straight quotes instead. (Tested in [`NonStandardQuotes.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/NonStandardQuotes.yml).) + +<!-- vale gitlab.NonStandardQuotes = YES --> + ### Placeholder text You might want to provide a command or configuration that @@ -677,22 +705,27 @@ use a URL like `https://docs.gitlab.com/charts/`. ### Anchor links -Each heading has an anchor link. For example, a topic with the title +Each topic title has an anchor link. For example, a topic with the title `## This is an example` has the anchor `#this-is-an-example`. -The first topic on a page (the `h1`) has an anchor link, +The first topic title on a page (the `h1`) has an anchor link, but do not use it. Link to the page instead. -If a heading has a [product tier badge](#product-tier-badges), -do not include it in the anchor link. For example, for the heading +If a topic title has a [product tier badge](#product-tier-badges), +do not include it in the anchor link. For example, for the topic `## This is an example **(FREE)**`, use the anchor `#this-is-an-example`. With Kramdown, you can add a custom ID to an HTML element, but these IDs don't work in `/help`, so you should not use them. +When you change topic title text, the anchor link changes. To avoid broken links: + +- Do not use step numbers in topic titles. +- When possible, do not use words that might change in the future. + #### Changing links and titles -When you change a heading, the anchor link changes. To ensure you update +When you change a topic title, the anchor link changes. To ensure you update any related links, search these directories: - `doc/*` @@ -823,7 +856,7 @@ To open either project or group settings: ```markdown 1. On the top bar, select **Main menu**, and: - - For a project, select ***Projects** and find your project. + - For a project, select **Projects** and find your project. - For a group, select **Groups** and find your group. 1. On the left sidebar, select **Settings > CI/CD**. 1. Expand **General pipelines**. @@ -1195,7 +1228,7 @@ Instead of adding a note: - Re-write the sentence as part of a paragraph. - Put the information into its own paragraph. -- Put the content under a new subheading. +- Put the content under a new topic title. If you must use a note, use this format: @@ -1311,6 +1344,7 @@ It renders on the GitLab documentation site as: > - Second item in the list ## Tabs +<!-- markdownlint-disable tabs-blank-lines --> On the docs site, you can format text so it's displayed as tabs. @@ -1329,6 +1363,7 @@ Here's some other content in tab two. ::EndTabs ``` +<!-- markdownlint-enable tabs-blank-lines --> This code renders on the GitLab documentation site as: @@ -1378,25 +1413,25 @@ When names change, it is more complicated to search or grep text that has line b ### Product tier badges -Tier badges are displayed as orange text next to a heading. These badges link to the GitLab +Tier badges are displayed as orange text next to a topic title. These badges link to the GitLab pricing page. For example:  You must assign a tier badge: -- To all H1 topic headings, except the pages under `doc/development/*`. -- To topic headings that don't apply to the same tier as the H1. +- To all H1 topic titles, except the pages under `doc/development/*`. +- To topic titles that don't apply to the same tier as the H1. -To add a tier badge to a heading, add the relevant tier badge -after the heading text. For example: +To add a tier badge to a topic title, add the relevant tier badge +after the title text. For example: ```markdown -# Heading title **(FREE)** +# Topic title **(FREE)** ``` Do not add tier badges inline with other text, except for [API attributes](../restful_api_styleguide.md). -The single source of truth for a feature should be the heading where the +The single source of truth for a feature should be the topic where the functionality is described. #### Available product tier badges diff --git a/doc/development/documentation/styleguide/word_list.md b/doc/development/documentation/styleguide/word_list.md index 65ad8dea688..d28972a644b 100644 --- a/doc/development/documentation/styleguide/word_list.md +++ b/doc/development/documentation/styleguide/word_list.md @@ -35,7 +35,7 @@ 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** +Spell out **two-factor authentication** in sentence case for the first use and in topic titles, 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. @@ -64,6 +64,23 @@ When you create a user, you choose an access level: **Regular**, **Auditor**, or Capitalize these words when you refer to the UI. Otherwise use lowercase. +## active voice + +Use active voice instead of passive. + +Use: + +- The contributor writes the documentation. + +Instead of: + +- The documentation is written by contributors. + +NOTE: +If you can add the phrase "by zombies" to the phrase, +the construction is passive. For example, `The button is selected by zombies` +is passive. `Zombies select the button` is active. + ## administrator Use **administrator access** instead of **admin** when talking about a user's access level. @@ -460,6 +477,10 @@ Do not use **foo** in product documentation. You can use it in our API and contr When possible, use present tense instead of future tense. 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)) +## GB, gigabytes + +For **GB** and **MB**, follow the [Microsoft guidance](https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/term-collections/bits-bytes-terms). + ## Geo Use title case for **Geo**. @@ -570,6 +591,15 @@ Do not use Latin abbreviations. Use **that is** instead. ([Vale](../testing.md#v Do not use **in order to**. Use **to** instead. ([Vale](../testing.md#vale) rule: [`Wordy.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/Wordy.yml)) +## -ing words + +Remove **-ing** words whenever possible. They can be difficult to translate, +and more precise terms are usually available. For example: + +- Instead of **The files using storage are deleted**, use **The files that use storage are deleted**. +- Instead of **Delete files using the Edit button**, use **Delete files by using the Edit button**. +- Instead of **Replicating your server is required**, use **You must replicate your server**. + ## issue Use lowercase for **issue**. @@ -582,6 +612,21 @@ Use lowercase for **issue board**. Use lowercase for **issue weights**. +## it + +When you use the word **it**, ensure the word it refers to is obvious. +If it's not obvious, repeat the word rather than using **it**. + +Use: + +- The field returns a connection. The field accepts four arguments. + +Instead of: + +- The field returns a connection. It accepts four arguments. + +See also [this, these, that, those](#this-these-that-those). + ## job Do not use **build** to be synonymous with **job**. A job is defined in the `.gitlab-ci.yml` file and runs as part of a pipeline. @@ -692,6 +737,10 @@ Do not use `master`. Use `main` when you need a sample [default branch name](#de **Might** means something has the probability of occurring. **May** gives permission to do something. Consider **can** instead of **may**. +## MB, megabytes + +For **MB** and **GB**, follow the [Microsoft guidance](https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/term-collections/bits-bytes-terms). + ## me, myself, mine 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)) @@ -720,24 +769,18 @@ Do not use **navigate**. Use **go** instead. For example: ## need to, should -Try to avoid **needs to**, because it's wordy. Avoid **should** when you can be more specific. If something is required, use **must**. +Try to avoid **needs to**, because it's wordy. If something is recommended, use **should** instead. If something is required, use **must**. Use: -- You must set the variable. -- Set the variable. +- You should set the variable. (recommended) +- You must set the variable. (required) +- Set the variable. (required) Instead of: - You need to set the variable. - -**Should** is acceptable for recommended actions or items, or in cases where an event may not -happen. For example: - -- Although you can configure the installation manually, you should use the express configuration to - avoid complications. -- You should see a success message in the console. Contact support if an error message appears - instead. +- We recommend that you set the variable. ## note that @@ -811,7 +854,7 @@ When writing about the Owner role: - Instead of: if you are an owner Do not use bold. - + Do not use **Owner permissions**. A user who is assigned the Owner role has a set of associated permissions. An Owner is the highest role a user can have. @@ -893,6 +936,10 @@ Instead of: - Select **Create user** or **Save changes** if you created a new user or edited an existing one respectively. +## review app + +Use lowercase for **review app**. + ## roles Do not use **roles** and [**permissions**](#permissions) interchangeably. Each user is assigned a role. Each role includes a set of permissions. @@ -981,7 +1028,11 @@ Use **setup** as a noun, and **set up** as a verb. For example: ## sign in -Use **sign in** instead of **sign on** or **log on** or **log in**. If the user interface has different words, use those. +Use **sign in** or **sign in to**. + +Do not use **sign on** or **sign into**, or **log on**, **log in**, or **log into**. + +If the user interface has different words, use those. You can use **single sign-on**. @@ -1108,6 +1159,14 @@ For example: See also [**enter**](#enter). +## units of measurement + +Use a space between the number and the unit of measurement. For example, **128 GB**. +([Vale](../testing.md#vale) rule: [`Units.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/Units.yml)) + +For other guidance, follow +[the Microsoft style guidelines](https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/term-collections/bits-bytes-terms). + ## update Use **update** for installing a newer **patch** version of the software only. For example: @@ -1173,7 +1232,26 @@ Instead of: - We created a feature for you to add widgets. -One exception: You can use **we recommend** instead of **it is recommended** or **GitLab recommends**. ([Vale](../testing.md#vale) rule: [`SubstitutionSuggestions.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/SubstitutionSuggestions.yml)) +([Vale](../testing.md#vale) rule: [`SubstitutionSuggestions.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/SubstitutionSuggestions.yml)) + +## while + +Use **while** to refer only to something occurring in time. For example, +**Leave the window open while the process runs.** + +Do not use **while** for comparison. For example, use: + +- Job 1 can run quickly. However, job 2 is more precise. + +Instead of: + +- While job 1 can run quickly, job 2 is more precise. + +For details, see the [Microsoft style guide](https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/w/while). + +## whilst + +Do not use **whilst**. Use [while](#while) instead. **While** is more succinct and easier for non-native English speakers to understand. ## whitelist @@ -1203,5 +1281,19 @@ Instead of: - Users can configure a pipeline. +## you can + +When possible, start sentences with an active verb instead of **you can**. +For example: + +- Use code review analytics to view merge request data. +- Create a board to organize your team tasks. +- Configure variables to restrict pushes to a repository. + +Use **you can** for optional actions. For example: + +- Use code review analytics to view metrics per merge request. You can also use the API. +- Enter the name and value pairs. You can add up to 20 pairs per streaming destination. + <!-- vale on --> <!-- markdownlint-enable --> |