diff options
Diffstat (limited to 'doc/development/documentation')
| -rw-r--r-- | doc/development/documentation/feature_flags.md | 30 | ||||
| -rw-r--r-- | doc/development/documentation/img/manual_build_docs_v14_3.png (renamed from doc/development/documentation/img/manual_build_docs.png) | bin | 14855 -> 14855 bytes | |||
| -rw-r--r-- | doc/development/documentation/index.md | 51 | ||||
| -rw-r--r-- | doc/development/documentation/redirects.md | 25 | ||||
| -rw-r--r-- | doc/development/documentation/review_apps.md | 2 | ||||
| -rw-r--r-- | doc/development/documentation/site_architecture/index.md | 2 | ||||
| -rw-r--r-- | doc/development/documentation/structure.md | 2 | ||||
| -rw-r--r-- | doc/development/documentation/styleguide/img/admin_access_level.png | bin | 0 -> 9821 bytes | |||
| -rw-r--r-- | doc/development/documentation/styleguide/index.md | 141 | ||||
| -rw-r--r-- | doc/development/documentation/styleguide/word_list.md | 109 | ||||
| -rw-r--r-- | doc/development/documentation/testing.md | 1 | ||||
| -rw-r--r-- | doc/development/documentation/workflow.md | 24 |
12 files changed, 283 insertions, 104 deletions
diff --git a/doc/development/documentation/feature_flags.md b/doc/development/documentation/feature_flags.md index 5a4d365ed20..c169af1958e 100644 --- a/doc/development/documentation/feature_flags.md +++ b/doc/development/documentation/feature_flags.md @@ -37,14 +37,14 @@ FLAG: | If the feature is... | Use this text | |--------------------------|---------------| -| Available | `On self-managed GitLab, by default this feature is available. To hide the feature, ask an administrator to [disable the <flag name> flag](<path to>/administration/feature_flags.md).` | -| Unavailable | `On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the <flag name> flag](<path to>/administration/feature_flags.md).` | -| Available, per-group | `On self-managed GitLab, by default this feature is available. To hide the feature per group, ask an administrator to [disable the <flag name> flag](<path to>/administration/feature_flags.md).` | -| Unavailable, per-group | `On self-managed GitLab, by default this feature is not available. To make it available per group, ask an administrator to [enable the <flag name> flag](<path to>/administration/feature_flags.md).` | -| Available, per-project | `On self-managed GitLab, by default this feature is available. To hide the feature per project or for your entire instance, ask an administrator to [disable the <flag name> flag](<path to>/administration/feature_flags.md).` | -| Unavailable, per-project | `On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, ask an administrator to [enable the <flag name> flag](<path to>/administration/feature_flags.md).` | -| Available, per-user | `On self-managed GitLab, by default this feature is available. To hide the feature per user, ask an administrator to [disable the <flag name> flag](<path to>/administration/feature_flags.md).` | -| Unavailable, per-user | `On self-managed GitLab, by default this feature is not available. To make it available per user, ask an administrator to [enable the <flag name> flag](<path to>/administration/feature_flags.md).` | +| Available | `On self-managed GitLab, by default this feature is available. To hide the feature, ask an administrator to [disable the feature flag](<path to>/administration/feature_flags.md) named <flag name>.` | +| Unavailable | `On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](<path to>/administration/feature_flags.md) named <flag name>.` | +| Available, per-group | `On self-managed GitLab, by default this feature is available. To hide the feature per group, ask an administrator to [disable the feature flag](<path to>/administration/feature_flags.md) named <flag name>.` | +| Unavailable, per-group | `On self-managed GitLab, by default this feature is not available. To make it available per group, ask an administrator to [enable the feature flag](<path to>/administration/feature_flags.md) named <flag name>.` | +| Available, per-project | `On self-managed GitLab, by default this feature is available. To hide the feature per project or for your entire instance, ask an administrator to [disable the feature flag](<path to>/administration/feature_flags.md) named <flag name>.` | +| Unavailable, per-project | `On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, ask an administrator to [enable the feature flag](<path to>/administration/feature_flags.md) named <flag name>.` | +| Available, per-user | `On self-managed GitLab, by default this feature is available. To hide the feature per user, ask an administrator to [disable the feature flag](<path to>/administration/feature_flags.md) named <flag name>.` | +| Unavailable, per-user | `On self-managed GitLab, by default this feature is not available. To make it available per user, ask an administrator to [enable the feature flag](<path to>/administration/feature_flags.md) named <flag name>.` | ### GitLab.com availability information @@ -67,7 +67,7 @@ When the state of a flag changes (for example, disabled by default to enabled by Possible version history entries are: ```markdown -> - [Introduced](issue-link) in GitLab X.X. [Deployed behind the <flag name> flag](../../administration/feature_flags.md), disabled by default. +> - [Introduced](issue-link) in GitLab X.X [with a flag](../../administration/feature_flags.md) named <flag name>. Disabled by default. > - [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. @@ -80,31 +80,31 @@ Possible version history entries are: The following examples show the progression of a feature flag. ```markdown -> Introduced in GitLab 13.7. [Deployed behind the `forti_token_cloud` flag](../../administration/feature_flags.md), disabled by default. +> Introduced in GitLab 13.7 [with a flag](../../administration/feature_flags.md) named `forti_token_cloud`. Disabled by default. FLAG: On self-managed GitLab, by default this feature is not available. To make it available, -ask an administrator to [enable the `forti_token_cloud` flag](../administration/feature_flags.md).` +ask an administrator to [enable the featured flag](../administration/feature_flags.md) named `forti_token_cloud`. The feature is not ready for production use. ``` When the feature is enabled in production, you can update the version history: ```markdown -> - Introduced in GitLab 13.7. [Deployed behind the `forti_token_cloud` flag](../../administration/feature_flags.md), disabled by default. +> - 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) GitLab 13.8. FLAG: On self-managed GitLab, by default this feature is available. To hide the feature per user, -ask an administrator to [disable the `forti_token_cloud` flag](../administration/feature_flags.md). +ask an administrator to [disable the feature flag](../administration/feature_flags.md) named `forti_token_cloud`. ``` And, when the feature is done and fully available to all users: ```markdown -> - Introduced in GitLab 13.7. [Deployed behind the `forti_token_cloud` flag](../../administration/feature_flags.md), disabled by default. +> - 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) GitLab 13.8. > - [Enabled on GitLab.com](https://gitlab.com/issue/etc) in GitLab 13.9. -> - [Feature flag `forti_token_cloud`](https://gitlab.com/issue/etc) removed in GitLab 14.0. +> - [Feature flag removed](https://gitlab.com/issue/etc) in GitLab 14.0. > - [Generally available](issue-link) in GitLab 14.0. ``` diff --git a/doc/development/documentation/img/manual_build_docs.png b/doc/development/documentation/img/manual_build_docs_v14_3.png Binary files differindex e366a2f7ec4..e366a2f7ec4 100644 --- a/doc/development/documentation/img/manual_build_docs.png +++ b/doc/development/documentation/img/manual_build_docs_v14_3.png diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index a597ea512c6..75538fe1fe7 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -108,23 +108,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w If you need help determining the correct stage, read [Ask for help](workflow.md#ask-for-help). -### Document type metadata - -Originally discussed in [this epic](https://gitlab.com/groups/gitlab-org/-/epics/1280), -each page should have a metadata tag called `type`. It can be one or more of the -following: - -- `index`: It consists mostly of a list of links to other pages. - [Example page](../../index.md). -- `concepts`: The background or context of a subject. - [Example page](../../topics/autodevops/index.md). -- `howto`: Specific use case instructions. - [Example page](../../ssh/index.md). -- `tutorial`: Learn a process/concept by doing. - [Example page](../../gitlab-basics/start-using-git.md). -- `reference`: A collection of information used as a reference to use a feature - or a functionality. [Example page](../../ci/yaml/index.md). - ### Redirection metadata The following metadata should be added when a page is moved to another location: @@ -154,7 +137,12 @@ Each page can have additional, optional metadata (set in the [default.html](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/fc3577921343173d589dfa43d837b4307e4e620f/layouts/default.html#L30-52) Nanoc layout), which is displayed at the top of the page if defined. -## Move or rename a page +### Deprecated metadata + +The `type` metadata parameter is deprecated but still exists in documentation +pages. You can safely remove the `type` metadata parameter and its values. + +## Move, rename, or delete a page See [redirects](redirects.md). @@ -214,8 +202,10 @@ with the following conventions: The help text follows the [Pajamas guidelines](https://design.gitlab.com/usability/helping-users/#formatting-help-content). -Use the following special cases depending on the context, ensuring all links -are inside `_()` so they can be translated: +#### Linking to `/help` in HAML + +Use the following special cases depending on the context, ensuring all link text +is inside `_()` so it can be translated: - Linking to a doc page. In its most basic form, the HAML code to generate a link to the `/help` page is: @@ -260,6 +250,27 @@ helpPagePath('user/permissions', { anchor: 'anchor-link' }) This is preferred over static paths, as the helper also works on instances installed under a [relative URL](../../install/relative_url.md). +#### Linking to `/help` in Ruby + +To link to the documentation from within Ruby code, use the following code block as a guide, ensuring all link text is inside `_()` so it can +be translated: + +```ruby +docs_link = link_to _('Learn more.'), help_page_url('user/permissions', anchor: 'anchor-link'), target: '_blank', rel: 'noopener noreferrer' +_('This is a text describing the option/feature in a sentence. %{docs_link}').html_safe % { docs_link: docs_link.html_safe } +``` + +In cases where you need to generate a link from outside of views/helpers, where the `link_to` and `help_page_url` methods are not available, use the following code block +as a guide where the methods are fully qualified: + +```ruby +docs_link = ActionController::Base.helpers.link_to _('Learn more.'), Rails.application.routes.url_helpers.help_page_url('user/permissions', anchor: 'anchor-link'), target: '_blank', rel: 'noopener noreferrer' +_('This is a text describing the option/feature in a sentence. %{docs_link}').html_safe % { docs_link: docs_link.html_safe } +``` + +Do not use `include ActionView::Helpers::UrlHelper` just to make the `link_to` method available as you might see in some existing code. Read more in +[issue 340567](https://gitlab.com/gitlab-org/gitlab/-/issues/340567). + ### GitLab `/help` tests Several [RSpec tests](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/features/help_pages_spec.rb) diff --git a/doc/development/documentation/redirects.md b/doc/development/documentation/redirects.md index eb6878f5870..ef94c33a276 100644 --- a/doc/development/documentation/redirects.md +++ b/doc/development/documentation/redirects.md @@ -15,13 +15,26 @@ description: Learn how to contribute to GitLab Documentation. # Redirects in GitLab documentation -Moving or renaming a document is the same as changing its location. Be sure -to assign a technical writer to any merge request that renames or moves a page. -Technical Writers can help with any questions and can review your change. +When you move, rename, or delete a page, you must add a redirect. Redirects reduce +how often users get 404s when visiting the documentation site from out-of-date links, like: + +- Bookmarks +- Links from external sites +- Links from old blog posts +- Links in the documentation site global navigation + +Add a redirect to ensure: -When moving or renaming a page, you must redirect browsers to the new page. -This ensures users find the new page, and have the opportunity to update their -bookmarks. +- Users see the new page and can update or delete their bookmark. +- External sites can update their links, especially sites that have automation that + check for redirecting links. +- The documentation site global navigation does not link to a missing page. + + The links in the global navigation are already tested in the `gitlab-docs` project. + If the redirect is missing, the `gitlab-docs` project's `main` branch might break. + +Be sure to assign a technical writer to any merge request that moves, renames, or deletes a page. +Technical Writers can help with any questions and can review your change. There are two types of redirects: diff --git a/doc/development/documentation/review_apps.md b/doc/development/documentation/review_apps.md index 2b8c412f165..a5094ea87f0 100644 --- a/doc/development/documentation/review_apps.md +++ b/doc/development/documentation/review_apps.md @@ -26,7 +26,7 @@ to render and preview the documentation locally. If a merge request has documentation changes, use the `review-docs-deploy` manual job to deploy the documentation review app for your merge request. - + The `review-docs-deploy*` job triggers a cross project pipeline and builds the docs site with your changes. When the pipeline finishes, the review app URL diff --git a/doc/development/documentation/site_architecture/index.md b/doc/development/documentation/site_architecture/index.md index cd69154217c..d1736e10000 100644 --- a/doc/development/documentation/site_architecture/index.md +++ b/doc/development/documentation/site_architecture/index.md @@ -230,7 +230,7 @@ reports. ## Monthly release process (versions) The docs website supports versions and each month we add the latest one to the list. -For more information, read about the [monthly release process](https://about.gitlab.com/handbook/engineering/ux/technical-writing/workflow/#monthly-documentation-releases). +For more information, read about the [monthly release process](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/doc/releases.md). ## Review Apps for documentation merge requests diff --git a/doc/development/documentation/structure.md b/doc/development/documentation/structure.md index a9b93997906..229dbb077fe 100644 --- a/doc/development/documentation/structure.md +++ b/doc/development/documentation/structure.md @@ -149,6 +149,8 @@ For the heading: If you do not put the full error in the title, include it in the body text. +If multiple causes or workarounds exist, consider putting them into a table format. + ## Other types of content There are other types of content in the GitLab documentation that don't diff --git a/doc/development/documentation/styleguide/img/admin_access_level.png b/doc/development/documentation/styleguide/img/admin_access_level.png Binary files differnew file mode 100644 index 00000000000..191ba78cd6c --- /dev/null +++ b/doc/development/documentation/styleguide/img/admin_access_level.png diff --git a/doc/development/documentation/styleguide/index.md b/doc/development/documentation/styleguide/index.md index 2cbecc91b20..72491ab3a33 100644 --- a/doc/development/documentation/styleguide/index.md +++ b/doc/development/documentation/styleguide/index.md @@ -1091,47 +1091,51 @@ However, they should be used sparingly because: - They are difficult and expensive to localize. - They cannot be read by screen readers. -If you do include an image in the documentation, ensure it provides value. -Don't use `lorem ipsum` text. Try to replicate how the feature would be -used in a real-world scenario, and [use realistic text](#fake-user-information). +When needed, use images to help the reader understand: -### Capture the image +- Where they are in a complicated process. +- How they should interact with the application. -Use images to help the reader understand where they are in a process, or how -they need to interact with the application. +### Capture the image When you take screenshots: -- **Capture the most relevant area of the page.** Don't include unnecessary white - space or areas of the page that don't help illustrate the point. The left - sidebar of the GitLab user interface can change, so don't include the sidebar - if it's not necessary. +- **Ensure it provides value.** Don't use `lorem ipsum` text. + Try to replicate how the feature would be used in a real-world scenario, and + [use realistic text](#fake-user-information). +- **Capture only the relevant UI.** Don't include unnecessary white + space or areas of the UI that don't help illustrate the point. The + sidebars in GitLab can change, so don't include + them in screenshots unless absolutely necessary. - **Keep it small.** If you don't need to show the full width of the screen, don't. - A value of 1000 pixels is a good maximum width for your screenshot image. + Reduce the size of your browser window as much as possible to keep elements close + together and reduce empty space. Try to keep the screenshot dimensions as small as possible. +- **Review how the image renders on the page.** Preview the image locally or use the +review app in the merge request. Make sure the image isn't blurry or overwhelming. - **Be consistent.** Coordinate screenshots with the other screenshots already on - a documentation page. For example, if other screenshots include the left - sidebar, include the sidebar in all screenshots. + a documentation page for a consistent reading experience. ### Save the image +- Resize any wide or tall screenshots if needed, but make sure the screenshot is + still clear after being resized and compressed. +- All images **must** be [compressed](#compress-images) to 100KB or less. + In many cases, 25-50KB or less is often possible without reducing image quality. - Save the image with a lowercase filename that's descriptive of the feature - or concept in the image. If the image is of the GitLab interface, append the - GitLab version to the filename, based on this format: - `image_name_vX_Y.png`. For example, for a screenshot taken from the pipelines - page of GitLab 11.1, a valid name is `pipelines_v11_1.png`. If you're adding an - illustration that doesn't include parts of the user interface, add the release - number corresponding to the release the image was added to; for an MR added to - 11.1's milestone, a valid name for an illustration is `devops_diagram_v11_1.png`. + or concept in the image: + - If the image is of the GitLab interface, append the GitLab version to the filename, + based on this format: `image_name_vX_Y.png`. For example, for a screenshot taken + from the pipelines page of GitLab 11.1, a valid name is `pipelines_v11_1.png`. + - If you're adding an illustration that doesn't include parts of the user interface, + add the release number corresponding to the release the image was added to. + For an MR added to 11.1's milestone, a valid name for an illustration is `devops_diagram_v11_1.png`. - Place images in a separate directory named `img/` in the same directory where the `.md` document that you're working on is located. - Consider using PNG images instead of JPEG. -- [Compress all PNG images](#compress-images). - Compress GIFs with <https://ezgif.com/optimize> or similar tool. - Images should be used (only when necessary) to illustrate the description of a process, not to replace it. -- Max image size: 100KB (GIFs included). -- See also how to link and embed [videos](#videos) to illustrate the - documentation. +- See also how to link and embed [videos](#videos) to illustrate the documentation. ### Add the image link to content @@ -1152,8 +1156,11 @@ known tool is [`pngquant`](https://pngquant.org/), which is cross-platform and open source. Install it by visiting the official website and following the instructions for your OS. +If you use macOS and want all screenshots to be compressed automatically, read +[One simple trick to make your screenshots 80% smaller](https://about.gitlab.com/blog/2020/01/30/simple-trick-for-smaller-screenshots/). + GitLab has a [Ruby script](https://gitlab.com/gitlab-org/gitlab/-/blob/master/bin/pngquant) -that you can use to automate the process. In the root directory of your local +that you can use to simplify the manual process. In the root directory of your local copy of `https://gitlab.com/gitlab-org/gitlab`, run in a terminal: - Before compressing, if you want, check that all documentation PNG images have @@ -1360,13 +1367,15 @@ Do not use words to describe the icon: ## Alert boxes -Use alert boxes to call attention to information. +Use alert boxes to call attention to information. Use them sparingly, and never have an alert box immediately follow another alert box. Alert boxes are generated when one of these words is followed by a line break: - `FLAG:` - `NOTE:` - `WARNING:` +- `INFO:` (Marketing only) +- `DISCLAIMER:` For example: @@ -1423,6 +1432,58 @@ It renders on the GitLab documentation site as: WARNING: This is something to be warned about. +### Info + +The Marketing team uses the `INFO` alert to add information relating +to sales and marketing efforts. + +The text in an `INFO:` alert always renders in a floating text box to the right of the text around it. +To view the rendered GitLab docs site, check the review app in the MR. You might need to move the text up or down +in the surrounding text, depending on where you'd like to floating box to appear. + +For example, if your page has text like this: + +```markdown +This is an introductory paragraph. GitLab uses the SSH protocol to securely communicate with Git. +When you use SSH keys to authenticate to the GitLab remote server, +you don't need to supply your username and password each time. + +INFO: +Here is some information. This information is an important addition to how you +work with GitLab and you might want to consider it. + +And here is another paragraph. GitLab uses the SSH protocol to securely communicate with Git. +When you use SSH keys to authenticate to the GitLab remote server, +you don't need to supply your username and password each time. + +And here is another paragraph. GitLab uses the SSH protocol to securely communicate with Git. +When you use SSH keys to authenticate to the GitLab remote server, +you don't need to supply your username and password each time. +``` + +It renders on the GitLab documentation site as: + +This is an introductory paragraph. GitLab uses the SSH protocol to securely communicate with Git. +When you use SSH keys to authenticate to the GitLab remote server, +you don't need to supply your username and password each time. + +INFO: +Here is some information. This information is an important addition to how you +work with GitLab and you might want to consider it. + +And here is another paragraph. GitLab uses the SSH protocol to securely communicate with Git. +When you use SSH keys to authenticate to the GitLab remote server, +you don't need to supply your username and password each time. + +And here is another paragraph. GitLab uses the SSH protocol to securely communicate with Git. +When you use SSH keys to authenticate to the GitLab remote server, +you don't need to supply your username and password each time. + +### Disclaimer + +Use to describe future functionality only. +For more information, see [Legal disclaimer for future features](#legal-disclaimer-for-future-features). + ## Blockquotes For highlighting a text inside a blockquote, use this format: @@ -1616,6 +1677,34 @@ For example: You can say that we plan to remove a feature. +#### Legal disclaimer for future features + +If you **must** write about features we have not yet delivered, put this exact disclaimer near the content it applies to. + +```markdown +DISCLAIMER: +This page contains information related to upcoming products, features, and functionality. +It is important to note that the information presented is for informational purposes only. +Please do not rely on this information for purchasing or planning purposes. +As with all projects, the items mentioned on this page are subject to change or delay. +The development, release, and timing of any products, features, or functionality remain at the +sole discretion of GitLab Inc. +``` + +It renders on the GitLab documentation site as: + +DISCLAIMER: +This page contains information related to upcoming products, features, and functionality. +It is important to note that the information presented is for informational purposes only. +Please do not rely on this information for purchasing or planning purposes. +As with all projects, the items mentioned on this page are subject to change or delay. +The development, release, and timing of any products, features, or functionality remain at the +sole discretion of GitLab Inc. + +If all of the content on the page is not available, use the disclaimer once at the top of the page. + +If the content in a topic is not ready, use the disclaimer in the topic. + ### Removing versions after each major release Whenever a major GitLab release occurs, we remove all version references diff --git a/doc/development/documentation/styleguide/word_list.md b/doc/development/documentation/styleguide/word_list.md index eafe0e7a1c2..f1e6a147571 100644 --- a/doc/development/documentation/styleguide/word_list.md +++ b/doc/development/documentation/styleguide/word_list.md @@ -29,9 +29,39 @@ Try to avoid using **above** when referring to an example or table in a document - In the previous example, the dog had fleas. -## admin, admin area +Do not use **above** when referring to versions of the product. Use [**later**](#later) instead. -Use **administration**, **administrator**, **administer**, or **Admin Area** instead. ([Vale](../testing.md#vale) rule: [`Admin.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/Admin.yml)) +- Do: In GitLab 14.4 and later... +- Do not: In GitLab 14.4 and above... +- Do not: In GitLab 14.4 and higher... + +## access level + +Access levels are different than [roles](#roles) or [permissions](#permissions). +When you create a user, you choose an access level: **Regular**, **Auditor**, or **Admin**. + +Capitalize these words when you refer to the UI. Otherwise use lowercase. + +## administrator + +Use **administrator** instead of **admin** when talking about a user's access level. +Use lowercase unless you are referring to the **Admin** access level you select in the UI. + +To view the administrator access type, in the GitLab UI, go to the Admin Area and select +**Users**. Then select **New user**. + + + +An **administrator** is not a [role](#roles) or [permission](#permissions). + +- Do: To do this thing, you must be an administrator. +- Do: To do this thing, you must have the administrator access level. +- Do not: To do this thing, you must have the Admin role. + +## Admin Area + +Use title case **Admin Area** to refer to the area of the UI that you access when you select **Menu > Admin**. +This area of the UI says **Admin Area** at the top of the page and on the menu. ## allow, enable @@ -54,9 +84,14 @@ in the handbook when writing about Alpha features. Instead of **and/or**, use **or** or rewrite the sentence to spell out both options. +## 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). + ## area -Use [**section**](#section) instead of **area**. The only exception is [the Admin Area](#admin-admin-area). +Use [**section**](#section) instead of **area**. The only exception is [the Admin Area](#admin-area). ## below @@ -150,8 +185,8 @@ When writing about the Developer role: - 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: at least the Developer role + - Do not: the Developer role or higher Do not use **Developer permissions**. A user who is assigned the Developer role has a set of associated permissions. @@ -207,7 +242,8 @@ Use lowercase for **epic board**. ## etc. -Try to avoid **etc.**. Be as specific as you can. Do not use **and so on** as a replacement. +Try to avoid **etc.**. Be as specific as you can. Do not use +[**and so on**](#and-so-on) as a replacement. - Do: You can update objects, like merge requests and issues. - Do not: You can update objects, like merge requests, issues, etc. @@ -220,8 +256,8 @@ Use **expand** instead of **open** when you are talking about expanding or colla Use **box** instead of **field** or **text box**. -- Avoid: In the **Variable name** field, enter `my text`. -- Use instead: In the **Variable name** box, enter `my text`. +- Do: In the **Variable name** box, enter `my text`. +- Do not: In the **Variable name** field, enter `my text`. ## foo @@ -265,8 +301,8 @@ When writing about the Guest role: - 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: at least the Guest role + - Do not: the Guest role or higher Do not use **Guest permissions**. A user who is assigned the Guest role has a set of associated permissions. @@ -282,15 +318,16 @@ Do not use **high availability** or **HA**. Instead, direct readers to the GitLa Do not use **higher** when talking about version numbers. -- Do: In GitLab 14.1 and later. -- Do not: In GitLab 14.1 and higher. +- Do: In GitLab 14.4 and later... +- Do not: In GitLab 14.4 and higher... +- Do not: In GitLab 14.4 and above... ## hit Don't use **hit** to mean **press**. -- Avoid: Hit the **ENTER** button. -- Use instead: Press **ENTER**. +- Do: Press **ENTER**. +- Do not: Hit the **ENTER** button. ## I @@ -326,8 +363,9 @@ If you want to use **CI** with the word **job**, use **CI/CD job** rather than * Use **later** when talking about version numbers. -- Avoid: In GitLab 14.1 and higher. -- Use instead: In GitLab 14.1 and later. +- Do: In GitLab 14.1 and later... +- Do not: In GitLab 14.1 and higher... +- Do not: In GitLab 14.1 and above... ## list @@ -354,8 +392,8 @@ When writing about the Maintainer role: - 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: at least the Maintainer role + - Do not: the Maintainer role or higher Do not use **Maintainer permissions**. A user who is assigned the Maintainer role has a set of associated permissions. @@ -416,6 +454,13 @@ Do not use **note that** because it's wordy. - Do: You can change the settings. - Do not: Note that you can change the settings. +## once + +The word **once** means **one time**. Don't use it to mean **after** or **when**. + +- Do: When the process is complete... +- Do not: Once the process is complete... + ## Owner When writing about the Owner role: @@ -429,7 +474,9 @@ Do not use **Owner permissions**. A user who is assigned the Owner role has a se ## permissions -Do not use **roles** and **permissions** interchangeably. Each user is assigned a role. Each role includes a set of permissions. +Do not use [**roles**](#roles) and **permissions** interchangeably. Each user is assigned a role. Each role includes a set of permissions. + +Permissions are not the same as [**access levels**](#access-level). ## please @@ -454,8 +501,8 @@ When writing about the Reporter role: - 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: at least the Reporter role + - Do not: the Reporter role or higher Do not use **Reporter permissions**. A user who is assigned the Reporter role has a set of associated permissions. @@ -465,12 +512,23 @@ Use title case for **Repository Mirroring**. ## roles -Do not use **roles** and **permissions** interchangeably. Each user is assigned a role. Each role includes a set of permissions. +Do not use **roles** and [**permissions**](#permissions) interchangeably. Each user is assigned a role. Each role includes a set of permissions. + +Roles are not the same as [**access levels**](#access-level). ## runner, runners Use lowercase for **runners**. These are the agents that run CI/CD jobs. See also [GitLab Runner](#gitlab-runner) and [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/233529). +## (s) + +Do not use **(s)** to make a word optionally plural. It can slow down comprehension. For example: + +Do: Select the jobs you want. +Do not: Select the job(s) you want. + +If you can select multiples of something, then write the word as plural. + ## sanity check Do not use **sanity check**. 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)) @@ -514,6 +572,13 @@ You can use **single sign-on**. Do not use **simply** or **simple**. If the user doesn't find the process to be simple, we lose their trust. ([Vale](../testing.md#vale) rule: [`Simplicity.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/Simplicity.yml)) +## since + +The word **since** indicates a timeframe. For example, **Since 1984, Bon Jovi has existed**. Don't use **since** to mean **because**. + +- Do: Because you have the Developer role, you can delete the widget. +- Do not: Since you have the Developer role, you can delete the widget. + ## slashes 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. diff --git a/doc/development/documentation/testing.md b/doc/development/documentation/testing.md index dfa2f3ed55a..13648a7c710 100644 --- a/doc/development/documentation/testing.md +++ b/doc/development/documentation/testing.md @@ -206,7 +206,6 @@ Vale returns three types of results: `suggestion`, `warning`, and `error`: (after the Technical Writing team completes its cleanup). Warnings don't break CI. See a list of [warning-level rules](https://gitlab.com/search?utf8=✓&snippets=false&scope=&repository_ref=master&search=path%3Adoc%2F.vale%2Fgitlab+Warning%3A&group_id=9970&project_id=278964). - **Error**-level results are Style Guide violations, and should contain clear explanations - about how to resolve the error. Errors break CI and are displayed in CI job output. of how to resolve the error. Errors break CI and are displayed in CI job output. See a list of [error-level rules](https://gitlab.com/search?utf8=✓&snippets=false&scope=&repository_ref=master&search=path%3Adoc%2F.vale%2Fgitlab+Error%3A&group_id=9970&project_id=278964). diff --git a/doc/development/documentation/workflow.md b/doc/development/documentation/workflow.md index 31c38bc1446..90c1137e5c5 100644 --- a/doc/development/documentation/workflow.md +++ b/doc/development/documentation/workflow.md @@ -99,7 +99,7 @@ The process involves the following: - Primary Reviewer. Review by a [code reviewer](https://about.gitlab.com/handbook/engineering/projects/) or other appropriate colleague to confirm accuracy, clarity, and completeness. This can be skipped for minor fixes without substantive content changes. -- Technical Writer (Optional). If not completed for a merge request prior to merging, must be scheduled +- 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). @@ -111,7 +111,7 @@ The process involves the following: - Ensure the appropriate labels are applied, including any required to pick a merge request into a release. - Ensure that, if there has not been a Technical Writer review completed or scheduled, they - [create the required issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Doc%20Review), assign to the Technical Writer of the given stage group, + [create the required issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Doc%20Review), assign it to the Technical Writer of the given stage group, and link it from the merge request. The process is reflected in the **Documentation** @@ -130,10 +130,10 @@ immediately after merge by the developer or maintainer. For this, create an issue using the [Doc Review description template](https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Doc%20Review) and link to it from the merged merge request that introduced the documentation change. -Circumstances where a regular pre-merge Technical Writer review might be skipped include: +Circumstances, where a regular pre-merge Technical Writer review might be skipped, include: -- There is a short amount of time left before the milestone release. If there are less than three days - remaining, seek a post-merge review and ping the writer via Slack to ensure the review is +- There is a short amount of time left before the milestone release. If less than three + days are remaining, seek a post-merge review and ping the writer via Slack to ensure the review is completed as soon as possible. - The size of the change is small and you have a high degree of confidence that early users of the feature (for example, GitLab.com users) can easily @@ -156,15 +156,15 @@ Remember: Ensure the following if skipping an initial Technical Writer review: -- That [product badges](styleguide/index.md#product-tier-badges) are applied. -- That the GitLab [version](styleguide/index.md#gitlab-versions) that - introduced the feature has been included. -- That changes to headings don't affect in-app hyperlinks. +- [Product badges](styleguide/index.md#product-tier-badges) are applied. +- The GitLab [version](styleguide/index.md#gitlab-versions) that + introduced the feature is included. +- Changes to headings don't affect in-app hyperlinks. - Specific [user permissions](../../user/permissions.md) are documented. -- That new documents are linked from higher-level indexes, for discoverability. -- Style guide is followed: +- New documents are linked from higher-level indexes, for discoverability. +- The style guide is followed: - For [directories and files](styleguide/index.md#work-with-directories-and-files). - For [images](styleguide/index.md#images). Merge requests that change the location of documentation must always be reviewed by a Technical -Writer prior to merging. +Writer before merging. |
