diff options
Diffstat (limited to 'doc/development/documentation')
20 files changed, 166 insertions, 201 deletions
diff --git a/doc/development/documentation/feature_flags.md b/doc/development/documentation/feature_flags.md index 87d2930dcb5..dae62fea603 100644 --- a/doc/development/documentation/feature_flags.md +++ b/doc/development/documentation/feature_flags.md @@ -1,5 +1,5 @@ --- -info: For assistance with this Style Guide page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-other-projects-and-subjects. +info: For assistance with this Style Guide page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. stage: none group: unassigned description: "GitLab development - how to document features deployed behind feature flags" @@ -34,7 +34,7 @@ Possible version history entries are: > - [Enabled on GitLab.com](issue-link) in GitLab X.X. > - [Enabled on GitLab.com](issue-link) in GitLab X.X. Available to GitLab.com administrators only. > - [Enabled on self-managed](issue-link) in GitLab X.X. -> - [Generally available](issue-link) in GitLab X.Y. [Feature flag `flag_name`](issue-link) removed. +> - [Generally available](issue-link) in GitLab X.Y. Feature flag `flag_name` removed. ``` You can combine entries if they happened in the same release: @@ -115,5 +115,5 @@ And, when the feature is done and fully available to all users: > - Introduced in GitLab 13.7 [with a flag](../../administration/feature_flags.md) named `forti_token_cloud`. Disabled by default. > - [Enabled on self-managed](https://gitlab.com/issue/etc) in GitLab 13.8. > - [Enabled on GitLab.com](https://gitlab.com/issue/etc) in GitLab 13.9. -> - [Generally available](issue-link) in GitLab 14.0. [Feature flag `forti_token_cloud`](issue-link) removed. +> - [Generally available](issue-link) in GitLab 14.0. Feature flag `forti_token_cloud` removed. ``` diff --git a/doc/development/documentation/graphql_styleguide.md b/doc/development/documentation/graphql_styleguide.md index ad19a40a3f5..1bd8b37ff5f 100644 --- a/doc/development/documentation/graphql_styleguide.md +++ b/doc/development/documentation/graphql_styleguide.md @@ -2,7 +2,7 @@ type: reference, dev stage: none group: Development -info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines" +info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines" description: "Writing styles, markup, formatting, and other standards for GraphQL API's GitLab Documentation." --- diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index 73c1874f09e..c52b3b5adae 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -1,7 +1,7 @@ --- stage: none group: Documentation Guidelines -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments description: Learn how to contribute to GitLab Documentation. --- @@ -94,7 +94,7 @@ belongs to, as well as an information block as described below: ```plaintext To determine the technical writer assigned to the Stage/Group associated with this page, see - https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments + https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments ``` For example: @@ -103,7 +103,7 @@ For example: --- stage: Example Stage group: Example Group -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- ``` @@ -171,7 +171,7 @@ contains an array of groups and their assigned technical writer. This task: To prepare an update to the `CODEOWNERS` file: -1. Update `lib/tasks/gitlab/tw/codeowners.rake` with the latest [TW team assignments](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments). +1. Update `lib/tasks/gitlab/tw/codeowners.rake` with the latest [TW team assignments](https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments). Make this update in a standalone merge request, as it runs a long pipeline and requires backend maintainer review. Make sure this is merged before you update `CODEOWNERS` in another merge request. @@ -465,7 +465,7 @@ RSpec.describe '<What I am taking screenshots of>', :js do #### Full page screenshots -To take a full page screenshot simply `visit the page` and perform any expectation on real content (to have capybara wait till the page is ready and not take a white screenshot). +To take a full page screenshot, `visit the page` and perform any expectation on real content (to have capybara wait till the page is ready and not take a white screenshot). #### Element screenshot diff --git a/doc/development/documentation/redirects.md b/doc/development/documentation/redirects.md index 1bc697f2878..1118dc97926 100644 --- a/doc/development/documentation/redirects.md +++ b/doc/development/documentation/redirects.md @@ -1,7 +1,7 @@ --- stage: none group: Documentation Guidelines -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments description: Learn how to contribute to GitLab Documentation. --- diff --git a/doc/development/documentation/restful_api_styleguide.md b/doc/development/documentation/restful_api_styleguide.md index 2991c1b3224..dc84f3a08dd 100644 --- a/doc/development/documentation/restful_api_styleguide.md +++ b/doc/development/documentation/restful_api_styleguide.md @@ -1,5 +1,5 @@ --- -info: For assistance with this Style Guide page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-other-projects-and-subjects. +info: For assistance with this Style Guide page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. stage: none group: unassigned description: 'Writing styles, markup, formatting, and other standards for the GitLab RESTful APIs.' diff --git a/doc/development/documentation/review_apps.md b/doc/development/documentation/review_apps.md index a50efceb307..cb04f0909c1 100644 --- a/doc/development/documentation/review_apps.md +++ b/doc/development/documentation/review_apps.md @@ -1,7 +1,7 @@ --- stage: none group: Documentation Guidelines -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments description: Learn how documentation review apps work. --- diff --git a/doc/development/documentation/site_architecture/deployment_process.md b/doc/development/documentation/site_architecture/deployment_process.md index 8a9c2e1e8d7..b5c3a59b0eb 100644 --- a/doc/development/documentation/site_architecture/deployment_process.md +++ b/doc/development/documentation/site_architecture/deployment_process.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Documentation deployments diff --git a/doc/development/documentation/site_architecture/folder_structure.md b/doc/development/documentation/site_architecture/folder_structure.md index 7f29d3fba9e..8a1d9b9fee3 100644 --- a/doc/development/documentation/site_architecture/folder_structure.md +++ b/doc/development/documentation/site_architecture/folder_structure.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Folder structure for documentation diff --git a/doc/development/documentation/site_architecture/global_nav.md b/doc/development/documentation/site_architecture/global_nav.md index 05e697869b9..37d10b16fcd 100644 --- a/doc/development/documentation/site_architecture/global_nav.md +++ b/doc/development/documentation/site_architecture/global_nav.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments description: "Learn how GitLab docs' global navigation works and how to add new items." --- diff --git a/doc/development/documentation/site_architecture/index.md b/doc/development/documentation/site_architecture/index.md index 44e4aac2756..d4553614fad 100644 --- a/doc/development/documentation/site_architecture/index.md +++ b/doc/development/documentation/site_architecture/index.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Documentation site architecture diff --git a/doc/development/documentation/styleguide/index.md b/doc/development/documentation/styleguide/index.md index bc79bf0fbe2..d629bc0b87e 100644 --- a/doc/development/documentation/styleguide/index.md +++ b/doc/development/documentation/styleguide/index.md @@ -1,5 +1,5 @@ --- -info: For assistance with this Style Guide page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-other-projects-and-subjects. +info: For assistance with this Style Guide page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. stage: none group: unassigned description: 'Writing styles, markup, formatting, and other standards for GitLab Documentation.' @@ -17,9 +17,9 @@ In addition to this page, the following resources can help you craft and contrib - [Doc contribution guidelines](../index.md) - [Recommended word list](word_list.md) - [Doc style and consistency testing](../testing.md) -- [UI text guidelines](https://design.gitlab.com/content/error-messages/) +- [Guidelines for UI error messages](https://design.gitlab.com/content/error-messages/) - [GitLab Handbook style guidelines](https://about.gitlab.com/handbook/communication/#writing-style-guidelines) -- [Microsoft Style Guide](https://docs.microsoft.com/en-us/style-guide/welcome/) +- [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) @@ -115,7 +115,7 @@ the documentation helps others efficiently accomplish tasks and solve problems. If you have questions when considering, authoring, or editing documentation, ask the Technical Writing team. They're available on Slack in `#docs` or in GitLab by -mentioning [the writer for](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments) +mentioning [the writer for](https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments) the applicable [DevOps stage or group](https://about.gitlab.com/handbook/product/categories/#devops-stages). Otherwise, forge ahead with your best effort. It does not need to be perfect; the team is happy to review and improve upon your content. Review the @@ -333,7 +333,7 @@ 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). +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://learn.microsoft.com/en-us/style-guide/numbers). ## Text @@ -465,10 +465,18 @@ When using code block style: ## Lists -- Always start list items with a capital letter, unless they're parameters or - commands that are in backticks, or similar. -- Always leave a blank line before and after a list. -- Begin a line with spaces (not tabs) to denote a [nested sub-item](#nesting-inside-a-list-item). +- Use a period after every sentence, including those that complete an introductory phrase. + Do not use semicolons or commas. +- Majority rules. Use either full sentences or all fragments. Avoid a mix. +- Always start list items with a capital letter. +- Separate the introductory phrase from explanatory text with a colon (`:`). For example: + + ```markdown + You can: + + - Do this thing. + - Do this other thing. + ``` ### Choose between an ordered or unordered list @@ -492,40 +500,27 @@ These things are imported: - Thing 3 ``` -You can choose to introduce either list with a colon, but you do not have to. - -### Markup +### List markup - Use dashes (`-`) for unordered lists instead of asterisks (`*`). -- Prefix `1.` to every item in an ordered list. When rendered, the list items - display with sequential numbering. - -### Punctuation - -- Don't add commas (`,`) or semicolons (`;`) to the ends of list items. -- If a list item is a complete sentence (with a subject and a verb), add a period at the end. -- Majority rules. If the majority of items do not end in a period, do not end any of the items in a period. -- Separate list items from explanatory text with a colon (`:`). For example: - - ```markdown - The list is as follows: - - - First item: this explains the first item. - - Second item: this explains the second item. - ``` +- Start every item in an ordered list with `1.`. When rendered, the list items + are sequential. +- Leave a blank line before and after a list. +- Begin a line with spaces (not tabs) to denote a [nested sub-item](#nesting-inside-a-list-item). ### Nesting inside a list item -It's possible to nest items under a list item, so that they render with the same -indentation as the list item. This can be done with: +You can nest items under a list item, so they render with the same +indentation as the list item. You can do this with: - [Code blocks](#code-blocks) - [Blockquotes](#blockquotes) - [Alert boxes](#alert-boxes) - [Images](#images) +- [Tabs](#tabs) -Items nested in lists should always align with the first character of the list -item. In unordered lists (using `-`), this means two spaces for each level of +Nested items should always align with the first character of the list +item. For unordered lists (using `-`), use two spaces for each level of indentation: ````markdown @@ -555,26 +550,9 @@ For ordered lists, use three spaces for each level of indentation: 1. Ordered list item 1 A line nested using 3 spaces to align with the `O` above. - -1. Ordered list item 2 - - > A quote block that will nest - > inside list item 2. - -1. Ordered list item 3 - - ```plaintext - a code block that nests inside list item 3 - ``` - -1. Ordered list item 4 - -  ```` -You can nest full lists inside other lists using the same rules as above. If you -want to mix types, that's also possible, if you don't mix items at the same -level: +You can nest lists in other lists. ```markdown 1. Ordered list item one. @@ -676,125 +654,66 @@ For other punctuation rules, refer to the [Pajamas Design System Punctuation section](https://design.gitlab.com/content/punctuation/). This is overridden by the [documentation-specific punctuation rules](#punctuation). -### Anchor links +## Links -Headings generate anchor links when rendered. `## This is an example` generates -the anchor `#this-is-an-example`. +Links help the docs adhere to the +[single source of truth](#documentation-is-the-single-source-of-truth-ssot) principle. -NOTE: -[Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/39717) in -GitLab 13.4, [product badges](#product-tier-badges) used in headings aren't -included in the generated anchor links. For example, when you link to -`## This is an example **(FREE)**`, use the anchor `#this-is-an-example`. +### Links within the same repository -Keep in mind that the GitLab user interface links to many documentation pages -and anchor links to take the user to the right spot. When you change -a heading, search `doc/*`, `app/views/*`, and `ee/app/views/*` for the old -anchor. If you do not fix these links, the [`ui-docs-lint` job](../testing.md#ui-link-tests) -in your merge request fails. - -Important: +To link to another page in the same repository, +use a relative file path. For example, `../user/gitlab_com/index.md`. -- Avoid crosslinking documentation to headings unless you need to link to a - specific section of the document. This avoids breaking anchors in the - future in case the heading is changed. -- If possible, avoid changing headings, because they're not only linked internally. - There are various links to GitLab documentation on the internet, such as - tutorials, presentations, StackOverflow posts, and other sources. -- Do not link to `h1` headings. +Use inline link Markdown markup `[Text](https://example.com)`, +rather than reference-style links, like `[Text][identifier]`. -Note that with Kramdown, it's possible to add a custom ID to an HTML element -with Markdown markup, but they don't work in `/help`. Because of this, don't use -this option. +Put the entire link on a single line so that [linters](../testing.md) can find it. -## Links +### Links in separate repositories -Links are important in GitLab documentation. Use links instead of -summarizing to help preserve a [single source of truth](#documentation-is-the-single-source-of-truth-ssot) -in GitLab documentation. - -We include guidance for links in these categories: - -- How to set up [anchor links](#anchor-links) for headings. -- How to set up [criteria](#basic-link-criteria) for configuring a link. -- What to set up when [linking to a `help`](../../documentation/index.md#linking-to-help) - page. -- How to set up [links to internal documentation](#links-to-internal-documentation) - for cross-references. -- How to set up [links to external documentation](#links-to-external-documentation) - for authoritative sources. -- When to use [links requiring permissions](#links-requiring-permissions). -- How to set up a [link to a video](#link-to-video). -- How to [link to specific lines of code](#link-to-specific-lines-of-code) - -### Basic link criteria - -- Use inline link Markdown markup `[Text](https://example.com)`. - It's easier to read, review, and maintain. Do not use `[Text][identifier]` reference-style links. -- Use meaningful anchor text. - For example, instead of writing something like `Read more about merge requests [here](LINK)`, - write `Read more about [merge requests](LINK)`. -- Put the entire link on a single line. Some of our [linters](../testing.md) do not - validate links when split over multiple lines, and incorrect or broken links could - slip through. - -### Links to internal documentation +To link to a page in a different repository, use an absolute URL. +For example, to link from a page in the GitLab repo to the Charts repo, +use a URL like `https://docs.gitlab.com/charts/`. -NOTE: -**Internal** refers to documentation in the same project. When linking to -documentation in separate projects (for example, linking to Omnibus documentation -from GitLab documentation), you must use absolute URLs. +### Anchor links -Do not use absolute URLs like `https://docs.gitlab.com/ee/index.html` to -cross-link to other documentation in the same project. Use relative links to -the file, like `../index.md`. (These are converted to HTML when the site is -rendered.) +Each heading has an anchor link. For example, a topic with the title +`## This is an example` has the anchor `#this-is-an-example`. -Relative linking enables crosslinks to work: +The first topic on a page (the `h1`) has an anchor link, +but do not use it. Link to the page instead. -- in Review Apps, local previews, and `/help`. -- when working on the documentation locally, so you can verify that they work as - early as possible in the process. -- in the GitLab user interface when browsing doc files in their respective - repositories. For example, the links displayed at - `https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/README.md`. +If a heading has a [product tier badge](#product-tier-badges), +do not include it in the anchor link. For example, for the heading +`## This is an example **(FREE)**`, use the anchor `#this-is-an-example`. -To link to internal documentation: +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. -- Use relative links to Markdown files in the same repository. -- Do not use absolute URLs or URLs from `docs.gitlab.com`. -- Use `../` to navigate to higher-level directories. -- Don't prepend `./` to links to files or directories. To link to a file in the - same directory or one of its sub-directories, use the syntax `path/to/file.md`. -- Don't link relative to root. For example, `/ee/user/gitlab_com/index.md`. +#### Changing links and titles - Don't: +When you change a heading, the anchor link changes. To ensure you update +any related links, search these directories: - - `https://docs.gitlab.com/ee/administration/geo/replication/troubleshooting.html` - - `/ee/administration/geo/replication/troubleshooting.md` - - `./troubleshooting.md` +- `doc/*` +- `app/views/*` +- `ee/app/views/*` - Do: `../../geo/replication/troubleshooting.md` +If you do not fix these links, the [`ui-docs-lint` job](../testing.md#ui-link-tests) +in your merge request fails. -- Always add the filename `file.md` at the end of the link with the `.md` - extension, not `.html`. +### Text for links - Don't: +Use descriptive text for links, rather than words like `here` or `this page.` - - `../../merge_requests/` - - `../../issues/tags.html` - - `../../issues/tags.html#stages` +For example, instead of: - Do: +- `For more information, see [this page](LINK).` +- `For more information, go [here](LINK).` - - `../../merge_requests/index.md` - - `../../issues/tags.md` - - `../../issues/tags.md#stages` - - `issues/tags.md` +Use: -NOTE: -Using the Markdown extension is necessary for the [`/help`](../index.md#gitlab-help) -section of GitLab. +- `For more information, see [merge requests](LINK)`. ### Links to external documentation @@ -900,6 +819,28 @@ To open group settings: 1. Expand **General pipelines**. ``` +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 group, select **Groups** and find your group. +1. On the left sidebar, select **Settings > CI/CD**. +1. Expand **General pipelines**. +``` + +To create a project: + +```markdown +1. On the top bar, select **Create new... > New project**. +``` + +To create a group: + +```markdown +1. On the top bar, select **Create new... > New group**. +``` + To open the Admin Area: ```markdown @@ -1127,6 +1068,14 @@ Do not use words to describe the icon: - Avoid: `Select **Erase job log** (the trash icon).` - Use instead: `Select **Erase job log** (**{remove}**).` This generates as: Select **Erase job log** (**{remove}**). +When the button doesn't have any hover text, you can describe the icon. +Follow up by creating a +[UX bug issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Bug) +to add hover text to the button to improve accessibility. + +- Avoid: `Select **{ellipsis_v}**.` +- Use instead: `Select the vertical ellipsis (**{ellipsis_v}**).` This generates as: Select the vertical ellipsis (**{ellipsis_v}**). + ## Videos Adding GitLab YouTube video tutorials to the documentation is highly diff --git a/doc/development/documentation/styleguide/word_list.md b/doc/development/documentation/styleguide/word_list.md index 029c7389290..65ad8dea688 100644 --- a/doc/development/documentation/styleguide/word_list.md +++ b/doc/development/documentation/styleguide/word_list.md @@ -1,7 +1,7 @@ --- stage: none group: Style Guide -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments description: 'Writing styles, markup, formatting, and other standards for GitLab Documentation.' --- @@ -17,7 +17,7 @@ recommends these word choices. In addition: For guidance not on this page, we defer to these style guides: -- [Microsoft Style Guide](https://docs.microsoft.com/en-us/style-guide/welcome/) +- [Microsoft Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/) - [Google Developer Documentation Style Guide](https://developers.google.com/style) <!-- vale off --> @@ -125,7 +125,7 @@ Instead of: - This feature enables users to add files to their repository. 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). +[View details in the Microsoft style guide](https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/a/allow-allows). ## Alpha @@ -141,7 +141,7 @@ Instead of **and/or**, use **or** or rewrite the sentence to spell out both opti ## and so on Do not use **and so on**. Instead, be more specific. For details, see -[the Microsoft style guide](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/a/and-so-on). +[the Microsoft style guide](https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/a/and-so-on). ## area @@ -218,7 +218,7 @@ Instead of: ## cannot, can not -Use **cannot** instead of **can not**. You can also use **can't**. +Use **cannot** instead of **can not**. See also [contractions](index.md#contractions). @@ -316,7 +316,7 @@ Do not use **Developer permissions**. A user who is assigned the Developer role ## 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 on **disable**. +See [the Microsoft style guide](https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/d/disable-disabled) for guidance on **disable**. 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)) ## disallow @@ -363,9 +363,13 @@ Do not use Latin abbreviations. Use **for example**, **such as**, **for instance Do not use **e-mail** with a hyphen. When plural, use **emails** or **email messages**. ([Vale](../testing.md#vale) rule: [`SubstitutionSuggestions.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/SubstitutionSuggestions.yml)) +## emojis + +Use **emojis** to refer to the plural form of **emoji**. + ## 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 on **enable**. +See [the Microsoft style guide](https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/e/enable-enables) for guidance on **enable**. 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)) ## enter @@ -509,13 +513,16 @@ For example, **Snowplow Guide**. Instead, speak about the feature itself, and ho When writing about the Guest role: - Use a capital **G**. -- Do not use bold. -- 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: +- Write it out: + - Use: if you are assigned the Guest role + - Instead of: if you are a guest + +- When the Guest role is the minimum required role: - Use: at least the Guest role - Instead of: the Guest role or higher +Do not use bold. + Do not use **Guest permissions**. A user who is assigned the Guest role has a set of associated permissions. ## handy @@ -656,13 +663,16 @@ Instead of: When writing about the Maintainer role: - Use a capital **M**. -- Do not use bold. -- 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: +- Write it out. + - Use: if you are assigned the Maintainer role + - Instead of: if you are a maintainer + +- When the Maintainer role is the minimum required role: - Use: at least the Maintainer role - Instead of: the Maintainer role or higher +Do not use bold. + Do not use **Maintainer permissions**. A user who is assigned the Maintainer role has a set of associated permissions. ## mankind @@ -796,11 +806,14 @@ For example, a log file might overwrite a log file of the same name. When writing about the Owner role: - Use a capital **O**. -- Do not use bold. -- 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**. +- Write it out. + - Use: if you are assigned 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. ## Package Registry @@ -818,7 +831,7 @@ Use lowercase for **personal access token**. ## please -Do not use **please**. For details, see the [Microsoft style guide](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/p/please). +Do not use **please**. For details, see the [Microsoft style guide](https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/p/please). ## press @@ -851,13 +864,16 @@ Use **register** instead of **sign up** when talking about creating an account. When writing about the Reporter role: - Use a capital **R**. -- Do not use bold. -- 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: +- Write it out. + - Use: if you are assigned the Reporter role + - Instead of: if you are a reporter + +- When the Reporter role is the minimum required role: - Use: at least the Reporter role - Instead of: the Reporter role or higher +Do not use bold. + Do not use **Reporter permissions**. A user who is assigned the Reporter role has a set of associated permissions. ## Repository Mirroring diff --git a/doc/development/documentation/testing.md b/doc/development/documentation/testing.md index 59a078bdec0..c801bb9f877 100644 --- a/doc/development/documentation/testing.md +++ b/doc/development/documentation/testing.md @@ -1,7 +1,7 @@ --- stage: none group: Documentation Guidelines -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments description: Learn how to contribute to GitLab Documentation. --- diff --git a/doc/development/documentation/topic_types/concept.md b/doc/development/documentation/topic_types/concept.md index a20bb93a97f..dfd003b642d 100644 --- a/doc/development/documentation/topic_types/concept.md +++ b/doc/development/documentation/topic_types/concept.md @@ -1,7 +1,7 @@ --- stage: none group: Style Guide -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Concept topic type diff --git a/doc/development/documentation/topic_types/index.md b/doc/development/documentation/topic_types/index.md index af3e66fe87a..8403fd26517 100644 --- a/doc/development/documentation/topic_types/index.md +++ b/doc/development/documentation/topic_types/index.md @@ -1,7 +1,7 @@ --- stage: none group: Style Guide -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Documentation topic types (CTRT) diff --git a/doc/development/documentation/topic_types/reference.md b/doc/development/documentation/topic_types/reference.md index 42f4f5f6f94..e7ee8b20925 100644 --- a/doc/development/documentation/topic_types/reference.md +++ b/doc/development/documentation/topic_types/reference.md @@ -1,7 +1,7 @@ --- stage: none group: Style Guide -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Reference topic type diff --git a/doc/development/documentation/topic_types/task.md b/doc/development/documentation/topic_types/task.md index 3488cb90cf9..60508fbf6ee 100644 --- a/doc/development/documentation/topic_types/task.md +++ b/doc/development/documentation/topic_types/task.md @@ -1,7 +1,7 @@ --- stage: none group: Style Guide -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Task topic type diff --git a/doc/development/documentation/topic_types/troubleshooting.md b/doc/development/documentation/topic_types/troubleshooting.md index 35187bd892e..e2136de2e06 100644 --- a/doc/development/documentation/topic_types/troubleshooting.md +++ b/doc/development/documentation/topic_types/troubleshooting.md @@ -1,7 +1,7 @@ --- stage: none group: Style Guide -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Troubleshooting topic type diff --git a/doc/development/documentation/versions.md b/doc/development/documentation/versions.md index 85733603cfe..12381b84c2c 100644 --- a/doc/development/documentation/versions.md +++ b/doc/development/documentation/versions.md @@ -1,5 +1,5 @@ --- -info: For assistance with this Style Guide page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-other-projects-and-subjects. +info: For assistance with this Style Guide page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. stage: none group: unassigned description: 'Writing styles, markup, formatting, and other standards for GitLab Documentation.' @@ -139,7 +139,7 @@ To remove a page: --- stage: Data Stores group: Global Search - info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments + info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments remove_date: '2022-08-02' redirect_to: '../newpath/to/file/index.md' --- @@ -154,7 +154,7 @@ To remove a page: 1. Remove the page's entry from the global navigation by editing [`navigation.yaml`](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/content/_data/navigation.yaml) in `gitlab-docs`. This content is removed from the documentation as part of the Technical Writing team's -[regularly scheduled tasks](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#regularly-scheduled-tasks). +[regularly scheduled tasks](https://about.gitlab.com/handbook/product/ux/technical-writing/#regularly-scheduled-tasks). ### Remove a topic @@ -179,7 +179,7 @@ To remove a topic: ``` This content is removed from the documentation as part of the Technical Writing team's -[regularly scheduled tasks](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#regularly-scheduled-tasks). +[regularly scheduled tasks](https://about.gitlab.com/handbook/product/ux/technical-writing/#regularly-scheduled-tasks). ## Which versions are removed diff --git a/doc/development/documentation/workflow.md b/doc/development/documentation/workflow.md index fb43a2e995a..85d3d5e9cfc 100644 --- a/doc/development/documentation/workflow.md +++ b/doc/development/documentation/workflow.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # How to update GitLab documentation @@ -13,7 +13,7 @@ Anyone can contribute to the GitLab documentation! You can create a merge reques accomplish their work with GitLab. If you are working on a feature or enhancement, use the -[feature workflow process described in the GitLab Handbook](https://about.gitlab.com/handbook/engineering/ux/technical-writing/workflow/#for-a-product-change). +[feature workflow process described in the GitLab Handbook](https://about.gitlab.com/handbook/product/ux/technical-writing/workflow/#for-a-product-change). ## How to update the docs @@ -54,7 +54,7 @@ Ask for help from the Technical Writing team if you: To identify someone who can help you: 1. Locate the Technical Writer for the relevant - [DevOps stage group](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments). + [DevOps stage group](https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments). 1. Either: - If urgent help is required, directly assign the Technical Writer in the issue or in the merge request. - If non-urgent help is required, ping the Technical Writer in the issue or merge request. @@ -86,7 +86,7 @@ merge documentation changes. Maintainers must make a good-faith effort to ensure - Meets the [Documentation Guidelines](index.md) and [Style Guide](styleguide/index.md). If the author or reviewer has any questions, they can mention the writer who is assigned to the relevant -[DevOps stage group](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments). +[DevOps stage group](https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments). The process involves the following: @@ -96,7 +96,7 @@ The process involves the following: - Technical Writer (Optional). If not completed for a merge request before merging, must be scheduled post-merge. Schedule post-merge reviews only if an urgent merge is required. To request a: - Pre-merge review, assign the Technical Writer listed for the applicable - [DevOps stage group](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments). + [DevOps stage group](https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments). - Post-merge review, see [Post-merge reviews](#post-merge-reviews). - Maintainer. For merge requests, Maintainers: - Can always request any of the above reviews. |