diff options
Diffstat (limited to 'doc/development/documentation')
| -rw-r--r-- | doc/development/documentation/feature_flags.md | 326 | ||||
| -rw-r--r-- | doc/development/documentation/index.md | 14 | ||||
| -rw-r--r-- | doc/development/documentation/site_architecture/index.md | 4 | ||||
| -rw-r--r-- | doc/development/documentation/site_architecture/release_process.md | 9 | ||||
| -rw-r--r-- | doc/development/documentation/structure.md | 12 | ||||
| -rw-r--r-- | doc/development/documentation/styleguide/index.md | 207 | ||||
| -rw-r--r-- | doc/development/documentation/styleguide/word_list.md | 214 | ||||
| -rw-r--r-- | doc/development/documentation/testing.md | 28 |
8 files changed, 409 insertions, 405 deletions
diff --git a/doc/development/documentation/feature_flags.md b/doc/development/documentation/feature_flags.md index 7fa80e2d0f5..b0fa6c3428c 100644 --- a/doc/development/documentation/feature_flags.md +++ b/doc/development/documentation/feature_flags.md @@ -1,14 +1,12 @@ --- 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: For assistance with this Style Guide page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-other-projects-and-subjects. description: "GitLab development - how to document features deployed behind feature flags" --- # Document features deployed behind feature flags -GitLab uses [Feature Flags](../feature_flags/index.md) to strategically roll +GitLab uses [feature flags](../feature_flags/index.md) to strategically roll out the deployment of its own features. The way we document a feature behind a feature flag depends on its state (enabled or disabled). When the state changes, the developer who made the change **must update the documentation** @@ -18,296 +16,92 @@ Every feature introduced to the codebase, even if it's behind a feature flag, must be documented. For context, see the [latest merge request that updated this guideline](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/47917#note_459984428). -## Criteria +When you document feature flags, you must: -According to the process of [deploying GitLab features behind feature flags](https://about.gitlab.com/handbook/product-development-flow/feature-flag-lifecycle/): +- [Add a note at the start of the topic](#use-a-note-to-describe-the-state-of-the-feature-flag). +- [Add version history text](#add-version-history-text). -> - _By default, feature flags should be off._ -> - _Feature flags should remain in the codebase for a short period as possible to reduce the need for feature flag accounting._ -> - _In order to build a final release and present the feature for self-managed users, the feature flag should be at least defaulted to on._ +## Use a note to describe the state of the feature flag -See how to document them below, according to the state of the flag: +Information about feature flags should be in a **Note** at the start of the topic (just below the version history). -- [Features disabled by default](#features-disabled-by-default). -- [Features that became enabled by default](#features-that-became-enabled-by-default). -- [Features directly enabled by default](#features-directly-enabled-by-default). -- [Features that can be enabled or disabled for a single project](#features-enabled-by-project). -- [Features with the feature flag removed](#features-with-flag-removed). +The note has three parts, and follows this structure: -The [`**(FREE SELF)**`](styleguide/index.md#product-tier-badges) badge or equivalent for -the feature's tier should be added to the line and heading that refers to -enabling/disabling feature flags as Admin access is required to do so, -therefore, it indicates that it cannot be done by regular users of GitLab.com. - -### Features disabled by default - -For features disabled by default, add or improve the docs with every change in line with the -[definition of done](../contributing/merge_request_workflow.md#definition-of-done). - -Include details of the feature flag in the documentation: - -- Say that it's disabled by default. -- Say whether it's enabled on GitLab.com. -- If the feature can be enabled/disabled for a single project, add the - [by-project information](#features-enabled-by-project). Otherwise, - do not say anything about it. -- Say whether it's recommended for production use. -- Document how to enable and disable it, preferably at the end of the file. -- Add a warning to the user saying that the feature might be disabled. - -For example, for a feature disabled by default, disabled on GitLab.com, cannot -be enabled for a single project, and is not ready for production use: - -````markdown -# Feature Name - -> - [Introduced](link-to-issue) in GitLab 12.0. -> - [Deployed behind a feature flag](<replace with path to>/user/feature_flags.md), disabled by default. -> - Disabled on GitLab.com. -> - Not recommended for production use. -> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#anchor-to-section). **(FREE SELF)** - -This in-development feature might not be available for your use. There can be -[risks when enabling features still in development](<replace with path to>/user/feature_flags.md#risks-when-enabling-features-still-in-development). -Refer to this feature's version history for more details. - -(...Regular content goes here...) - -<!-- Add this at the end of the file --> - -### Enable or disable <Feature Name> **(FREE SELF)** - -<Feature Name> is under development and not ready for production use. It is -deployed behind a feature flag that is **disabled by default**. -[GitLab administrators with access to the GitLab Rails console](<replace with path to>/administration/feature_flags.md) -can enable it. - -To enable it: - -```ruby -Feature.enable(:<feature flag>) -``` - -To disable it: - -```ruby -Feature.disable(:<feature flag>) -``` -```` - -Adjust the blurb according to the state of the feature you're documenting. -Replace `<Feature name>`, `**(FREE SELF)**`, `<feature flag>`, and -`<replace with path to>`, and `#anchor-to-section` accordingly. - -### Features that became enabled by default - -For features that were released disabled by default but became enabled by -default: - -- Say that it became enabled by default. -- Say whether it's enabled on GitLab.com. -- If the feature can be enabled/disabled for a single project, add the - [by-project information](#features-enabled-by-project). Otherwise, - do not say anything about it. -- Say whether it's recommended for production use. -- Document how to disable and enable it, preferably at the end of the file. -- Add a warning to the user saying that the feature might be disabled. - -For example, for a feature initially deployed disabled by default, that became -enabled by default, that is enabled on GitLab.com, and is ready for production -use: - -````markdown -# Feature Name - -> - [Introduced](link-to-issue) in GitLab 12.0. -> - [Deployed behind a feature flag](<replace with path to>/user/feature_flags.md), disabled by default. -> - [Enabled by default](link-to-issue) in GitLab 12.1. -> - Enabled on GitLab.com. -> - Recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#anchor-to-section). **(FREE SELF)** - -There can be -[risks when disabling released features](<replace with path to>/user/feature_flags.md#risks-when-disabling-released-features). -Refer to this feature's version history for more details. - -(...Regular content goes here...) - -<!-- Add this at the end of the file --> - -### Enable or disable <Feature Name> **(FREE SELF)** - -<Feature Name> is under development but ready for production use. -It is deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](<replace with path to>/administration/feature_flags.md) -can opt to disable it. - -To enable it: - -```ruby -Feature.enable(:<feature flag>) -``` - -To disable it: - -```ruby -Feature.disable(:<feature flag>) +```markdown +FLAG: +<Self-managed GitLab availability information.> <GitLab.com availability information.> +<This feature is not ready for production use.> ``` -```` - -Adjust the blurb according to the state of the feature you're documenting. -Replace `<Feature name>`, `**(FREE SELF)**`, `<feature flag>`, -`<replace with path to>`, and `#anchor-to-section` accordingly. - -### Features directly enabled by default -For features enabled by default: +### Self-managed GitLab availability information -- Say it's enabled by default. -- Say whether it's enabled on GitLab.com. -- If the feature can be enabled/disabled for a single project, add the - [by-project information](#features-enabled-by-project). Otherwise, - do not say anything about it. -- Say whether it's recommended for production use. -- Document how to disable and enable it, preferably at the end of the file. -- Add a warning to the user saying that the feature might be disabled. +| 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).` | -For example, for a feature enabled by default, enabled on GitLab.com, that -cannot be enabled for a single project, and is ready for production use: +### GitLab.com availability information -````markdown -# Feature Name +| If the feature is... | Use this text | +|-------------------------------------|---------------| +| Available | `On GitLab.com, this feature is available.` | +| Available to GitLab.com admins only | `On GitLab.com, this feature is available but can be configured by GitLab.com administrators only.` +| Unavailable | `On GitLab.com, this feature is not available.`| -> - [Introduced](link-to-issue) in GitLab 12.0. -> - [Deployed behind a feature flag](<replace with path to>/user/feature_flags.md), enabled by default. -> - Enabled on GitLab.com. -> - Recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#anchor-to-section). **(FREE SELF)** +### Optional information -There can be -[risks when disabling released features](<replace with path to>/user/feature_flags.md#risks-when-disabling-released-features). -Refer to this feature's version history for more details. +If needed, you can add this sentence: -(...Regular content goes here...) +`You should not use this feature for production environments.` -<!-- Add this at the end of the file --> +## Add version history text -### Enable or disable <Feature Name> **(FREE SELF)** - -<Feature Name> is under development but ready for production use. -It is deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](<replace with path to>/administration/feature_flags.md) -can opt to disable it. - -To enable it: - -```ruby -Feature.enable(:<feature flag>) -``` +When the state of a flag changes (for example, disabled by default to enabled by default), add the change to the version history. -To disable it: - -```ruby -Feature.disable(:<feature flag>) -``` -```` - -Adjust the blurb according to the state of the feature you're documenting. -Replace `<Feature name>`, `**(FREE SELF)**`, `<feature flag>`, -`<replace with path to>`, and `#anchor-to-section` accordingly. - -### Features enabled by project - -If the feature can be enabled/disabled for a single project, include in the -version history note: +Possible version history entries are: ```markdown -> - It can be enabled or disabled for a single project. +> - [Enabled on GitLab.com](issue-link) in GitLab X.X and is ready for production use. +> - [Enabled on GitLab.com](issue-link) in GitLab X.X and is ready for production use. Available to GitLab.com administrators only. +> - [Enabled with <flag name> flag](issue-link) for self-managed GitLab in GitLab X.X and is ready for production use. +> - [Feature flag <flag name> removed](issue-line) in GitLab X.X. ``` -Then add the by-project code to the code blocks: - -Enable code: +## Feature flag documentation examples -```ruby -# For the instance -Feature.enable(:<feature flag>) -# For a single project -Feature.enable(:<feature flag>, Project.find(<project id>)) -``` +The following examples show the progression of a feature flag. -Disable code: +```markdown +> Introduced in GitLab 13.7. -```ruby -# For the instance -Feature.disable(:<feature flag>) -# For a single project -Feature.disable(:<feature flag>, Project.find(<project id>)) +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).` +The feature is not ready for production use. ``` -For example, for a feature enabled by default, enabled on GitLab.com, that can -be enabled by project, and is ready for production use: +If it were to be updated in the future to enable its use in production, you can update the version history: -````markdown -# Feature Name - -> - [Introduced](link-to-issue) in GitLab 12.0. -> - [Deployed behind a feature flag](<replace with path to>/user/feature_flags.md), enabled by default. -> - Enabled on GitLab.com. -> - Can be enabled or disabled for a single project. -> - Recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#anchor-to-section). **(FREE SELF)** - -There can be -[risks when disabling released features](<replace with path to>/user/feature_flags.md#risks-when-disabling-released-features). -Refer to this feature's version history for more details. - -(...Regular content goes here...) - -<!-- Add this at the end of the file --> - -### Enable or disable <Feature Name> **(FREE SELF)** - -<Feature Name> is under development but ready for production use. -It is deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](<replace with path to>/administration/feature_flags.md) -can opt to disable it. - -To enable it: +```markdown +> - Introduced in GitLab 13.7. +> - [Enabled with `forti_token_cloud` flag](https://gitlab.com/issue/etc) for self-managed GitLab in GitLab X.X and ready for production use. -```ruby -# For the instance -Feature.enable(:<feature flag>) -# For a single project -Feature.enable(:<feature flag>, Project.find(<project id>)) +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). ``` -To disable it: +And, when the feature is done and fully available to all users: -```ruby -# For the instance -Feature.disable(:<feature flag>) -# For a single project -Feature.disable(:<feature flag>, Project.find(<project id>)) +```markdown +> - Introduced in GitLab 13.7. +> - [Enabled on GitLab.com](https://gitlab.com/issue/etc) in GitLab X.X and is ready for production use. +> - [Enabled with `forti_token_cloud` flag](https://gitlab.com/issue/etc) for self-managed GitLab in GitLab X.X and is ready for production use. +> - [Feature flag `forti_token_cloud`](https://gitlab.com/issue/etc) removed in GitLab X.X. ``` -```` - -Adjust the blurb according to the state of the feature you're documenting. -Replace `<Feature name>`, `**(FREE SELF)**`, `<feature flag>`, -`<replace with path to>`, and `#anchor-to-section` accordingly. - -### Features with flag removed - -Once the feature is ready and the flag has been removed, clean up the -documentation. Remove the feature flag mention keeping only a note that -mentions the flag in the version history notes: - -````markdown -# Feature Name - -> - [Introduced](link-to-issue) in GitLab 12.0. -> - [Feature flag removed](link-to-issue) in GitLab 12.2. - -(...Regular content...) - -```` diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index 91215ca21b4..59a1b8c7b99 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -41,7 +41,7 @@ run only the jobs that match the type of contribution. If your contribution cont **only** documentation changes, then only documentation-related jobs run, and the pipeline completes much faster than a code contribution. -If you are submitting documentation-only changes to Runner, Omnibus, or Charts, +If you are submitting documentation-only changes to Omnibus or Charts, the fast pipeline is not determined automatically. Instead, create branches for docs-only merge requests using the following guide: @@ -152,12 +152,7 @@ comments: false 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: - -- `reading_time`: If you want to add an indication of the approximate reading - time of a page, you can set `reading_time` to `true`. This uses a simple - [algorithm](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/lib/helpers/reading_time.rb) - to calculate the reading time based on the number of words. +Nanoc layout), which is displayed at the top of the page if defined. ## Move or rename a page @@ -209,8 +204,7 @@ To add a redirect: bundle exec rake "gitlab:docs:redirect[doc/user/search/old_file.md, https://example.com]" ``` - Alternatively, you can omit the arguments, and you'll be asked to enter - their values: + Alternatively, you can omit the arguments and be asked to enter their values: ```shell bundle exec rake gitlab:docs:redirect @@ -475,7 +469,7 @@ If you want to know the in-depth details, here's what's really happening: The following GitLab features are used among others: -- [Manual actions](../../ci/yaml/index.md#whenmanual) +- [Manual jobs](../../ci/jobs/job_control.md#create-a-job-that-must-be-run-manually) - [Multi project pipelines](../../ci/pipelines/multi_project_pipelines.md) - [Review Apps](../../ci/review_apps/index.md) - [Artifacts](../../ci/yaml/index.md#artifacts) diff --git a/doc/development/documentation/site_architecture/index.md b/doc/development/documentation/site_architecture/index.md index a1e08a9c19b..046de5c6d86 100644 --- a/doc/development/documentation/site_architecture/index.md +++ b/doc/development/documentation/site_architecture/index.md @@ -60,7 +60,7 @@ as such the docs for CE and EE are now identical. For historical reasons and in order not to break any existing links throughout the internet, we still maintain the CE docs (`https://docs.gitlab.com/ce/`), although it is hidden from the website, and is now a symlink to the EE docs. When -[Pages supports redirects](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/24), +[Support wildcard redirects](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/500) is resolved, we can remove this completely. ## Assets @@ -241,7 +241,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](release_process.md). +For more information, read about the [monthly release process](https://about.gitlab.com/handbook/engineering/ux/technical-writing/workflow/#monthly-documentation-releases). ## Review Apps for documentation merge requests diff --git a/doc/development/documentation/site_architecture/release_process.md b/doc/development/documentation/site_architecture/release_process.md deleted file mode 100644 index 46c74335932..00000000000 --- a/doc/development/documentation/site_architecture/release_process.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -redirect_to: 'https://about.gitlab.com/handbook/engineering/ux/technical-writing/workflow/#monthly-documentation-releases' -remove_date: '2021-07-12' ---- - -This file was moved to [another location](https://about.gitlab.com/handbook/engineering/ux/technical-writing/workflow/#monthly-documentation-releases). - -<!-- This redirect file can be deleted after <2021-07-12>. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/documentation/structure.md b/doc/development/documentation/structure.md index ac934673ee2..a9b93997906 100644 --- a/doc/development/documentation/structure.md +++ b/doc/development/documentation/structure.md @@ -183,8 +183,8 @@ A paragraph that explains what the tutorial does, and the expected outcome. To create a website: -- [Step 1: Do the first task](#do-the-first-task) -- [Step 2: Do the second task](#do-the-second-task) +1. [Do the first task](#do-the-first-task) +1. [Do the second task](#do-the-second-task) Prerequisites (optional): @@ -197,8 +197,8 @@ Prerequisites (optional): To do step 1: 1. First step. -2. Another step. -3. Another step. +1. Another step. +1. Another step. ## Do the second task @@ -207,8 +207,8 @@ Before you begin, make sure you have [done the first task](#do-the-first-task). To do step 2: 1. First step. -2. Another step. -3. Another step. +1. Another step. +1. Another step. ``` ### Get started diff --git a/doc/development/documentation/styleguide/index.md b/doc/development/documentation/styleguide/index.md index a5345f3b52d..4e548179b9e 100644 --- a/doc/development/documentation/styleguide/index.md +++ b/doc/development/documentation/styleguide/index.md @@ -1,7 +1,5 @@ --- -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: For assistance with this Style Guide page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-other-projects-and-subjects. description: 'Writing styles, markup, formatting, and other standards for GitLab Documentation.' --- @@ -39,7 +37,7 @@ documentation. ### The documentation includes all information Include problem-solving actions that may address rare cases or be considered -_risky_, but provide proper context through fully-detailed +risky, but provide proper context through fully detailed warnings and caveats. This kind of content should be included as it could be helpful to others and, when properly explained, its benefits outweigh the risks. If you think you have found an exception to this rule, contact the @@ -96,7 +94,7 @@ of truth and explain why it is important. ### Docs-first methodology -We employ a _documentation-first methodology_. This method ensures the documentation +We employ a documentation-first methodology. This method ensures the documentation remains a complete and trusted resource, and makes communicating about the use of GitLab more efficient. @@ -129,22 +127,14 @@ the documentation. All GitLab documentation is written using [Markdown](https://en.wikipedia.org/wiki/Markdown). -The [documentation website](https://docs.gitlab.com) uses GitLab Kramdown as its -Markdown rendering engine. For a complete Kramdown reference, see the -[GitLab Markdown Kramdown Guide](https://about.gitlab.com/handbook/markdown-guide/). - -The [`gitlab-kramdown`](https://gitlab.com/gitlab-org/gitlab_kramdown) Ruby gem -plans to support all [GitLab Flavored Markdown](../../../user/markdown.md) in the future, which is -all Markdown supported for display in the GitLab application itself. For now, use -regular Markdown and follow the rules in the linked style guide. - -Kramdown-specific markup (for example, `{:.class}`) doesn't render -properly on GitLab instances under [`/help`](../index.md#gitlab-help). +The [documentation website](https://docs.gitlab.com) uses [GitLab Kramdown](https://gitlab.com/gitlab-org/gitlab_kramdown), +a "flavored" Kramdown engine to render pages from Markdown to HTML. The use of Kramdown's +features is limited by our linters, so, use regular Markdown and follow the rules in the +linked style guide. You can't use Kramdown-specific markup (for example, `{:.class}`). ### HTML in Markdown -Hard-coded HTML is valid, although it's discouraged from being used while we -have `/help`. HTML is permitted if: +Hard-coded HTML is valid, although it's discouraged from being used. HTML is permitted if: - There's no equivalent markup in Markdown. - Advanced tables are necessary. @@ -232,8 +222,8 @@ Put files for a specific product area into the related folder: When working with directories and files: 1. When you create a new directory, always start with an `index.md` file. - Don't use another filename and _do not_ create `README.md` files. -1. _Do not_ use special characters and spaces, or capital letters in file + Don't use another filename and do not create `README.md` files. +1. Do not use special characters and spaces, or capital letters in file names, directory names, branch names, and anything that generates a path. 1. When creating or renaming a file or directory and it has more than one word in its name, use underscores (`_`) instead of spaces or dashes. For example, @@ -300,16 +290,11 @@ Do not include the same information in multiple places. ## Language -GitLab documentation should be clear and easy to understand. Avoid unnecessary words. +GitLab documentation should be clear and easy to understand. +- Avoid unnecessary words. - Be clear, concise, and stick to the goal of the topic. - Write in US English with US grammar. (Tested in [`British.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/British.yml).) -- Rewrite to avoid wordiness: - - there is - - there are - - enables you to - - in order to - - because of the fact that ### Capitalization @@ -325,35 +310,20 @@ Use sentence case. For example: When referring to specific user interface text, like a button label or menu item, use the same capitalization that's displayed in the user interface. Standards for this content are listed in the [Pajamas Design System Content section](https://design.gitlab.com/content/punctuation/) -and typically match what's called for in this Documentation Style Guide. +and typically match what's mentioned in this Documentation Style Guide. If you think the user interface text contains style mistakes, create an issue or an MR to propose a change to the user interface text. #### Feature names -- *Feature names are typically lowercase*, like those describing actions and - types of objects in GitLab. For example: - - epics - - issues - - issue weights - - merge requests - - milestones - - reorder issues - - runner, runners, shared runners - - a to-do item (tested in [`ToDo.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/ToDo.yml)) +- *Feature names are typically lowercase*. - *Some features are capitalized*, typically nouns naming GitLab-specific - capabilities or tools. For example: - - GitLab CI/CD - - Repository Mirroring - - Value Stream Analytics - - the To-Do List - - the Web IDE - - Geo - - GitLab Runner (see [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/233529) for details) - -Document any exceptions in this style guide. If you're not sure, ask a GitLab -Technical Writer so that they can help decide and document the result. + capabilities or tools. + +See the [word list](word_list.md) for details. + +If the term is not in the word list, ask a GitLab Technical Writer for advice. Do not match the capitalization of terms or phrases on the [Features page](https://about.gitlab.com/features/) or [features.yml](https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/features.yml) @@ -374,24 +344,14 @@ Follow the capitalization style listed at the authoritative source for the entity, which may use non-standard case styles. For example: GitLab and npm. -Use forms of *sign in*, instead of *log in* or *login*. For example: - -- Sign in to GitLab. -- Open the sign-in page. - -Exceptions to this rule include the concept of *single sign-on* and -references to user interface elements. For example: - -- To sign in to product X, enter your credentials, and then select **Log in**. - ### Fake user information You may need to include user information in entries such as a REST call or user profile. -_Do not_ use real user information or email addresses in GitLab documentation. For email -addresses and names, do use: +Do not use real user information or email addresses in GitLab documentation. For email +addresses and names, use: -- _Email addresses_: Use an email address ending in `example.com`. -- _Names_: Use strings like `example_username`. Alternatively, use diverse or +- Email addresses: Use an email address ending in `example.com`. +- Names: Use strings like `example_username`. Alternatively, use diverse or non-gendered names with common surnames, such as `Sidney Jones`, `Zhang Wei`, or `Alex Garcia`. @@ -492,14 +452,14 @@ Follow these guidelines for punctuation: | Rule | Example | |------------------------------------------------------------------|--------------------------------------------------------| -| Avoid semicolons. Use two sentences instead. | _That's the way that the world goes 'round. You're up one day and the next you're down._ -| Always end full sentences with a period. | _For a complete overview, read through this document._ | -| Always add a space after a period when beginning a new sentence. | _For a complete overview, check this doc. For other references, check out this guide._ | +| Avoid semicolons. Use two sentences instead. | That's the way that the world goes 'round. You're up one day and the next you're down. +| Always end full sentences with a period. | For a complete overview, read through this document. | +| Always add a space after a period when beginning a new sentence. | For a complete overview, check this doc. For other references, check out this guide. | | 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 tabs for indentation. Use spaces instead. You can configure your code editor to output spaces instead of tabs when pressing the tab key. | --- | -| Use serial commas (_Oxford commas_) before the final _and_ or _or_ in a list of three or more items. (Tested in [`OxfordComma.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/OxfordComma.yml).) | _You can create new issues, merge requests, and milestones._ | -| Always add a space before and after dashes when using it in a sentence (for replacing a comma, for example). | _You should try this - or not._ | -| When a colon is part of a sentence, always use lowercase after the colon. | _Linked issues: a way to create a relationship between issues._ | +| Use serial commas (Oxford commas) before the final **and** or **or** in a list of three or more items. (Tested in [`OxfordComma.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/OxfordComma.yml).) | You can create new issues, merge requests, and milestones. | +| Always add a space before and after dashes when using it in a sentence (for replacing a comma, for example). | You should try this - or not. | +| When a colon is part of a sentence, always use lowercase after the colon. | Linked issues: a way to create a relationship between issues. | <!-- vale gitlab.Repetition = YES --> @@ -529,6 +489,20 @@ When the docs are generated, the output is: To stop the command, press <kbd>Control</kbd>+<kbd>C</kbd>. +### Text entered in the UI + +If you want the user to type something in the UI, use backticks. For example: + +```plaintext +In the **Commit message** box, type `This is my merge request`. +``` + +Backticks are more precise than quotes. For example, in this string: + +- In the **Commit message** box, type "This is my merge request." + +It's not clear whether the user should include the period in the string. + ### Spaces between words Use only standard spaces between words. The search engine for the documentation @@ -776,11 +750,11 @@ Valid for Markdown content only, not for front matter entries: "This sentence 'quotes' something in a quote". For other punctuation rules, refer to the -[GitLab UX guide](https://design.gitlab.com/content/punctuation/). +[Pajamas Design System Punctuation section](https://design.gitlab.com/content/punctuation/). ## Headings -- Add _only one H1_ in each document, by adding `#` at the beginning of +- Add only one H1 in each document, by adding `#` at the beginning of it (when using Markdown). The `h1` becomes the document `<title>`. - Start with an `h2` (`##`), and respect the order `h2` > `h3` > `h4` > `h5` > `h6`. Never skip the hierarchy level, such as `h2` > `h4` @@ -879,16 +853,16 @@ We include guidance for links in these categories: ### 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]`. + It's easier to read, review, and maintain. Do not use `[Text][identifier]` reference-style links. -- Use [meaningful anchor texts](https://www.futurehosting.com/blog/links-should-have-meaningful-anchor-text-heres-why/). - For example, instead of writing something like `Read more about GitLab Issue Boards [here](LINK)`, - write `Read more about [GitLab Issue Boards](LINK)`. +- Use [meaningful anchor text](https://www.futurehosting.com/blog/links-should-have-meaningful-anchor-text-heres-why/). + For example, instead of writing something like `Read more about merge requests [here](LINK)`, + write `Read more about [merge requests](LINK)`. ### Links to internal documentation NOTE: -_Internal_ refers to documentation in the same project. When linking to +**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. @@ -1020,8 +994,8 @@ the commit link ensures the user lands on the line you're referring to. The **Permalink** button, displayed when viewing a file in a project, provides a link to the most recent commit of that file. -- _Do_: `[link to line 3](https://gitlab.com/gitlab-org/gitlab/-/blob/11f17c56d8b7f0b752562d78a4298a3a95b5ce66/.gitlab/issue_templates/Feature%20proposal.md#L3)` -- _Don't_: `[link to line 3](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/issue_templates/Feature%20proposal.md#L3).` +- Do: `[link to line 3](https://gitlab.com/gitlab-org/gitlab/-/blob/11f17c56d8b7f0b752562d78a4298a3a95b5ce66/.gitlab/issue_templates/Feature%20proposal.md#L3)` +- Don't: `[link to line 3](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/issue_templates/Feature%20proposal.md#L3).` If that linked expression has changed line numbers due to additional commits, you can still search the file for that query. In this case, update the @@ -1082,13 +1056,13 @@ they need to interact with the application. When you take screenshots: -- _Capture the most relevant area of the page._ Don't include unnecessary white +- **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. -- _Keep it small._ If you don't need to show the full width of the screen, don't. +- **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. -- _Be consistent._ Coordinate screenshots with the other screenshots already on +- **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. @@ -1107,8 +1081,8 @@ When you take screenshots: - 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. +- 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. @@ -1123,7 +1097,7 @@ documentation site. For accessibility and SEO, use [descriptions](https://webaim that: - Are accurate, succinct, and unique. -- Don't use _image of…_ or _graphic of…_ to describe the image. +- Don't use **image of** or **graphic of** to describe the image. ### Compress images @@ -1196,7 +1170,7 @@ embedded videos take up a lot of space on the page and can be distracting to rea To embed a video: 1. Copy the code from this procedure and paste it into your Markdown file. Leave a - blank line above and below it. Do _not_ edit the code (don't remove or add any spaces). + blank line above and below it. Do not edit the code (don't remove or add any spaces). 1. In YouTube, visit the video URL you want to display. Copy the regular URL from your browser (`https://www.youtube.com/watch?v=VIDEO-ID`) and replace the video title and link in the line under `<div class="video-fallback">`. @@ -1377,8 +1351,13 @@ example: Use alert boxes to call attention to information. -Alert boxes are generated when the words `NOTE:` or `WARNING:` are followed by a -line break. For example: +Alert boxes are generated when one of these words is followed by a line break: + +- `FLAG:` +- `NOTE:` +- `WARNING:` + +For example: ```markdown NOTE: @@ -1391,6 +1370,11 @@ To display an alert box for multiple paragraphs, lists, or headers, use Alert boxes render only on the GitLab documentation site (<https://docs.gitlab.com>). In the GitLab product help, alert boxes appear as plain text. +### Flag + +Use this alert type to describe a feature's availability. For information about how to format +`FLAG` alerts, see [Document features deployed behind feature flags](../feature_flags.md). + ### Note Use notes sparingly. Too many notes can make topics difficult to scan. @@ -1481,17 +1465,18 @@ application: Use these verbs for specific uses with user interface elements: -| Recommended | Used for | Replaces | -|:--------------------|:--------------------------------------|:---------------------------| -| _select_ | buttons, links, menu items, dropdowns | "click, "press," "hit" | -| _select_ or _clear_ | checkboxes | "enable", "click", "press" | -| _expand_ | expandable sections | "open" | +| Recommended | Used for | Replaces | +|:--------------------|:--------------------------------------|:----------------------| +| select | buttons, links, menu items, dropdowns | click, press, hit | +| select or clear | checkboxes | enable, click, press | +| expand | expandable sections | open | +| turn on or turn off | toggles | flip, enable, disable | ### Other Verbs | Recommended | Used for | Replaces | |:------------|:--------------------------------|:----------------------| -| _go to_ | making a browser go to location | "navigate to", "open" | +| go to | making a browser go to location | navigate to, open | ## GitLab versions @@ -1624,6 +1609,20 @@ For example: - In GitLab 12.2 and earlier, ... - In GitLab 11.6 and later, ... +### Promising features in future versions + +Do not promise to deliver features in a future release. For example, avoid phrases like, +"Support for this feature is planned." + +We cannot guarantee future feature work, and promises +like these can raise legal issues. Instead, say that an issue exists. +For example: + +- Support for improvements is tracked `[in this issue](LINK)`. +- You cannot do this thing, but `[an issue exists](LINK)` to change this behavior. + +You can say that we plan to remove a feature. + ### Removing versions after each major release Whenever a major GitLab release occurs, we remove all version references @@ -1682,17 +1681,17 @@ badges and tooltips (`<span class="badge-trigger free">`). #### Available product tier badges -| Tier in which feature is available | Tier badge | -|:--------------------------------------------------------------------------|:----------------------| -| GitLab Free self-managed and SaaS, and higher tiers | `**(FREE)**` | -| GitLab Premium self-managed and SaaS, and their higher tiers | `**(PREMIUM)**` | -| GitLab Ultimate self-managed and SaaS | `**(ULTIMATE)**` | -| _Only_ GitLab Free self-managed and higher tiers (no SaaS-based tiers) | `**(FREE SELF)**` | -| _Only_ GitLab Premium self-managed and higher tiers (no SaaS-based tiers) | `**(PREMIUM SELF)**` | -| _Only_ GitLab Ultimate self-managed (no SaaS-based tiers) | `**(ULTIMATE SELF)**` | -| _Only_ GitLab Free SaaS and higher tiers (no self-managed instances) | `**(FREE SAAS)**` | -| _Only_ GitLab Premium SaaS and higher tiers (no self-managed instances) | `**(PREMIUM SAAS)**` | -| _Only_ GitLab Ultimate SaaS (no self-managed instances) | `**(ULTIMATE SAAS)**` | +| Tier in which feature is available | Tier badge | +|:------------------------------------------------------------------------|:----------------------| +| GitLab Free self-managed and SaaS, and higher tiers | `**(FREE)**` | +| GitLab Premium self-managed and SaaS, and their higher tiers | `**(PREMIUM)**` | +| GitLab Ultimate self-managed and SaaS | `**(ULTIMATE)**` | +| Only GitLab Free self-managed and higher tiers (no SaaS-based tiers) | `**(FREE SELF)**` | +| Only GitLab Premium self-managed and higher tiers (no SaaS-based tiers) | `**(PREMIUM SELF)**` | +| Only GitLab Ultimate self-managed (no SaaS-based tiers) | `**(ULTIMATE SELF)**` | +| Only GitLab Free SaaS and higher tiers (no self-managed instances) | `**(FREE SAAS)**` | +| Only GitLab Premium SaaS and higher tiers (no self-managed instances) | `**(PREMIUM SAAS)**` | +| Only GitLab Ultimate SaaS (no self-managed instances) | `**(ULTIMATE SAAS)**` | Topics that mention the `gitlab.rb` file are referring to self-managed instances of GitLab. To prevent confusion, include the relevant `TIER SELF` diff --git a/doc/development/documentation/styleguide/word_list.md b/doc/development/documentation/styleguide/word_list.md index 3fba9078bab..9e921bb30f0 100644 --- a/doc/development/documentation/styleguide/word_list.md +++ b/doc/development/documentation/styleguide/word_list.md @@ -17,6 +17,12 @@ For guidance not on this page, we defer to these style guides: <!-- vale off --> <!-- markdownlint-disable --> +## @mention + +Try to avoid. Say "mention" instead, and consider linking to the +[mentions topic](../../../user/project/issues/issue_data_and_actions.md#mentions). +Don't use `code formatting`. + ## above Try to avoid extra words when referring to an example or table in a documentation page, but if required, use **previously** instead. @@ -35,6 +41,13 @@ Try to avoid, unless you are talking about security-related features. For exampl 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). +## Alpha + +Uppercase. For example: **The XYZ feature is in Alpha.** or **This Alpha release is ready to test.** + +You might also want to link to [this section](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha-beta-ga) +in the handbook when writing about Alpha features. + ## and/or Instead of **and/or**, use or or rewrite the sentence to spell out both options. @@ -43,10 +56,29 @@ Instead of **and/or**, use or or rewrite the sentence to spell out both options. Try to avoid extra words when referring to an example or table in a documentation page, but if required, use **following** instead. +## Beta + +Uppercase. For example: **The XYZ feature is in Beta.** or **This Beta release is ready to test.** + +You might also want to link to [this section](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha-beta-ga) +in the handbook when writing about Beta features. + ## blacklist Do not use. Another option is **denylist**. ([Vale](../testing.md#vale) rule: [`InclusionCultural.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionCultural.yml)) +## board + +Use lowercase for **boards**, **issue boards**, and **epic boards**. + +## checkbox + +One word, **checkbox**. Do not use **check box**. + +## CI/CD + +Always uppercase. No need to spell out on first use. + ## currently Do not use when talking about the product or its features. The documentation describes the product as it is today. ([Vale](../testing.md#vale) rule: [`CurrentStatus.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/CurrentStatus.yml)) @@ -56,6 +88,7 @@ Do not use when talking about the product or its features. The documentation des When writing about the Developer role: - Use a capital **D**. +- Do not use bold. - 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: @@ -69,6 +102,13 @@ Do not use **Developer permissions**. A user who is assigned the Developer role See [the Microsoft style guide](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/d/disable-disabled) for guidance. Use **inactive** or **off** instead. ([Vale](../testing.md#vale) rule: [`InclusionAbleism.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionAbleism.yml)) +## earlier + +Use when talking about version numbers. + +- Avoid: In GitLab 14.1 and lower. +- Use instead: In GitLab 14.1 and earlier. + ## easily Do not use. If the user doesn't find the process to be easy, we lose their trust. @@ -86,24 +126,51 @@ Do not use **e-mail** with a hyphen. When plural, use **emails** or **email mess See [the Microsoft style guide](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/e/enable-enables) for guidance. Use **active** or **on** instead. ([Vale](../testing.md#vale) rule: [`InclusionAbleism.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionAbleism.yml)) +## epic + +Lowercase. + +## epic board + +Lowercase. + +## etc. + +Try to avoid. Be as specific as you can. Do not use **and so on** as a replacement. + +- Avoid: You can update objects, like merge requests, issues, etc. +- Use instead: You can update objects, like merge requests and issues. + +## foo + +Do not use in product documentation. You can use it in our API and contributor documentation, but try to use a clearer and more meaningful example instead. + ## future tense When possible, use present tense instead. For example, use `after you execute this command, GitLab displays the result` instead of `after you execute this command, GitLab will display the result`. ([Vale](../testing.md#vale) rule: [`FutureTense.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/FutureTense.yml)) +## Geo + +Title case. + ## GitLab -Do not make possessive (GitLab's). This guidance follows [GitLab Brand Guidelines](https://about.gitlab.com/handbook/marketing/corporate-marketing/brand-activation/brand-guidelines/#trademark). +Do not make possessive (GitLab's). This guidance follows [GitLab Trademark Guidelines](https://about.gitlab.com/handbook/marketing/corporate-marketing/brand-activation/trademark-guidelines/). -### GitLab.com +## GitLab.com Refers to the GitLab instance managed by GitLab itself. -### GitLab SaaS +## GitLab SaaS Refers to the product license that provides access to GitLab.com. Does not refer to the GitLab instance managed by GitLab itself. -### GitLab self-managed +## GitLab Runner + +Title case. This is the product you install. See also [runners](#runner-runners) and [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/233529). + +## GitLab self-managed Refers to the product license for GitLab instances managed by customers themselves. @@ -112,6 +179,7 @@ Refers to the product license for GitLab instances managed by customers themselv 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: @@ -128,6 +196,13 @@ Do not use. If the user doesn't find the feature or process to be handy, we lose Do not use. Instead, direct readers to the GitLab [reference architectures](../../../administration/reference_architectures/index.md) for information about configuring GitLab for handling greater amounts of users. +## higher + +Do not use when talking about version numbers. + +- Avoid: In GitLab 14.1 and higher. +- Use instead: In GitLab 14.1 and later. + ## I 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)) @@ -136,11 +211,52 @@ Do not use first-person singular. Use **you**, **we**, or **us** instead. ([Vale Do not use Latin abbreviations. Use **that is** instead. ([Vale](../testing.md#vale) rule: [`LatinTerms.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/LatinTerms.yml)) +## in order to + +Do not use. Use **to** instead. ([Vale](../testing.md#vale) rule: [`Wordy.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/Wordy.yml)) + +## issue + +Lowercase. + +## issue board + +Lowercase. + +## issue weights + +Lowercase. + +## 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. + +If you want to use **CI** with the word **job**, use **CI/CD job** rather than **CI job**. + +## later + +Use when talking about version numbers. + +- Avoid: In GitLab 14.1 and higher. +- Use instead: In GitLab 14.1 and later. + +## log in, log on + +Do not use. Use [sign in](#sign-in) instead. If the user interface has **Log in**, you can use it. + +## lower + +Do not use when talking about version numbers. + +- Avoid: In GitLab 14.1 and lower. +- Use instead: In GitLab 14.1 and earlier. + ## Maintainer 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: @@ -173,11 +289,38 @@ Do not use first-person singular. Use **you**, **we**, or **us** instead. ([Vale Lowercase. If you use **MR** as the acronym, spell it out on first use. +## milestones + +Lowercase. + +## need to, should + +Try to avoid. If something is required, use **must**. + +- Avoid: You need to set the variable. +- Use instead: You must set the variable. Or: 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. + +## note that + +Do not use. + +- Avoid: Note that you can change the settings. +- Use instead: You can change the settings. + ## Owner 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**. @@ -200,6 +343,7 @@ Do not use. Doing so may negatively affect other users and contributors, which i 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: @@ -208,10 +352,18 @@ When writing about the Reporter role: Do not use **Reporter permissions**. A user who is assigned the Reporter role has a set of associated permissions. +## Repository Mirroring + +Title case. + ## roles Do not use roles and permissions interchangeably. Each user is assigned a role. Each role includes a set of permissions. +## runner, runners + +Lowercase. 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). + ## sanity check Do not use. Use **check for completeness** instead. ([Vale](../testing.md#vale) rule: [`InclusionAbleism.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionAbleism.yml)) @@ -227,6 +379,12 @@ Use **setup** as a noun, and **set up** as a verb. For example: - Your remote office setup is amazing. - To set up your remote office correctly, consider the ergonomics of your work area. +## sign in + +Use instead of **sign on** or **log on** or **log in**. If the user interface has different words, use those. + +You can use **single sign-on**. + ## simply, simple Do not use. If the user doesn't find the process to be simple, we lose their trust. @@ -245,17 +403,57 @@ Use instead of **sub-group**. ## that -Do not use. For example: +Do not use when describing a noun. For example: -- Avoid: The file that you save... +- Avoid: The file **that** you save... - Use instead: The file you save... +See also [this, these, that, those](#this-these-that-those). + +## terminal + +Lowercase. For example: + +- Open a terminal. +- From a terminal, run the `docker login` command. + +## there is, there are + +Try to avoid. These phrases hide the subject. + +- Avoid: There are holes in the bucket. +- Use instead: The bucket has holes. + ## they Avoid the use of gender-specific pronouns, unless referring to a specific person. Use a singular [they](https://developers.google.com/style/pronouns#gender-neutral-pronouns) as a gender-neutral pronoun. +## this, these, that, those + +Always follow these words with a noun. For example: + +- Avoid: **This** improves performance. +- Use instead: **This setting** improves performance. + +- Avoid: **These** are the best. +- Use instead: **These pants** are the best. + +- Avoid: **That** is the one you are looking for. +- Use instead: **That Jedi** is the one you are looking for. + +- Avoid: **Those** need to be configured. +- Use instead: **Those settings** need to be configured. (Or even better, **Configure those settings.**) + +## to-do item + +Use lowercase. ([Vale](../testing.md#vale) rule: [`ToDo.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/ToDo.yml)) + +## To-Do List + +Use title case. ([Vale](../testing.md#vale) rule: [`ToDo.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/ToDo.yml)) + ## useful Do not use. If the user doesn't find the process to be useful, we lose their trust. @@ -264,6 +462,10 @@ Do not use. If the user doesn't find the process to be useful, we lose their tru Do not use. Use **use** instead. It's more succinct and easier for non-native English speakers to understand. +## Value Stream Analytics + +Title case. + ## via Do not use Latin abbreviations. Use **with**, **through**, or **by using** instead. ([Vale](../testing.md#vale) rule: [`LatinTerms.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/LatinTerms.yml)) diff --git a/doc/development/documentation/testing.md b/doc/development/documentation/testing.md index ddd44801ae9..2ade6c1e71d 100644 --- a/doc/development/documentation/testing.md +++ b/doc/development/documentation/testing.md @@ -224,6 +224,27 @@ guidelines: | UI text from GitLab | Verify it correctly matches the UI, then: If it does not match the UI, update it. If it matches the UI, but the UI seems incorrect, create an issue to see if the UI needs to be fixed. If it matches the UI and seems correct, add it to the [vale spelling exceptions list](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/spelling-exceptions.txt). | | UI text from a third-party product | Rewrite the sentence to avoid it, or [add the vale exception code in-line](#disable-vale-tests). | +#### Vale readability score + +In [`ReadingLevel.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/ReadingLevel.yml), +we have implemented +[the Flesch-Kincaid grade level test](https://readable.com/blog/the-flesch-reading-ease-and-flesch-kincaid-grade-level/) +to determine the readability of our documentation. + +As a general guideline, the lower the score, the more readable the documentation. +For example, a page that scores `12` before a set of changes, and `9` after, indicates an iterative improvement to readability. The score is not an exact science, but is meant to help indicate the +general complexity level of the page. + +The readability score is calculated by using the following formula: + +```plaintext +(.39 x ASL) + (11.8 x ASW) – 15.59 +``` + +- `ASL` is average sentence length (the number of words divided by the number of sentences). +- `ASW` is the average number of syllables per word (the number of syllables divided by the number of words). +- The score excludes headings, code blocks, and lists. + ### Install linters At a minimum, install [markdownlint](#markdownlint) and [Vale](#vale) to match the checks run in @@ -285,11 +306,14 @@ To configure Vale in your editor, install one of the following as appropriate: In the extension's settings: + <!-- vale gitlab.Spelling = NO --> + - Select the **Use CLI** checkbox. - - In the <!-- vale gitlab.Spelling = NO --> **Config** setting, enter an absolute + - In the **Config** setting, enter an absolute path to [`.vale.ini`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.vale.ini) in one of the cloned GitLab repositories on your computer. - <!-- vale gitlab.Spelling = YES --> + + <!-- vale gitlab.Spelling = YES --> - In the **Path** setting, enter the absolute path to the Vale binary. In most cases, `vale` should work. To find the location, run `which vale` in a terminal. |