diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2020-11-19 08:27:35 +0000 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2020-11-19 08:27:35 +0000 |
commit | 7e9c479f7de77702622631cff2628a9c8dcbc627 (patch) | |
tree | c8f718a08e110ad7e1894510980d2155a6549197 /doc/development/documentation | |
parent | e852b0ae16db4052c1c567d9efa4facc81146e88 (diff) | |
download | gitlab-ce-0bddc398e06691ecd2db73d0c570a122a6585fe8.tar.gz |
Add latest changes from gitlab-org/gitlab@13-6-stable-eev13.6.0-rc42
Diffstat (limited to 'doc/development/documentation')
-rw-r--r-- | doc/development/documentation/feature_flags.md | 3 | ||||
-rw-r--r-- | doc/development/documentation/graphql_styleguide.md | 2 | ||||
-rw-r--r-- | doc/development/documentation/index.md | 272 | ||||
-rw-r--r-- | doc/development/documentation/restful_api_styleguide.md | 29 | ||||
-rw-r--r-- | doc/development/documentation/site_architecture/deployment_process.md | 6 | ||||
-rw-r--r-- | doc/development/documentation/site_architecture/global_nav.md | 5 | ||||
-rw-r--r-- | doc/development/documentation/site_architecture/index.md | 8 | ||||
-rw-r--r-- | doc/development/documentation/site_architecture/release_process.md | 9 | ||||
-rw-r--r-- | doc/development/documentation/structure.md | 9 | ||||
-rw-r--r-- | doc/development/documentation/styleguide.md | 2062 | ||||
-rw-r--r-- | doc/development/documentation/styleguide/index.md | 1999 | ||||
-rw-r--r-- | doc/development/documentation/testing.md | 292 | ||||
-rw-r--r-- | doc/development/documentation/workflow.md | 20 |
13 files changed, 2362 insertions, 2354 deletions
diff --git a/doc/development/documentation/feature_flags.md b/doc/development/documentation/feature_flags.md index 0f03ceeb4b5..5bc3e1d59e2 100644 --- a/doc/development/documentation/feature_flags.md +++ b/doc/development/documentation/feature_flags.md @@ -30,8 +30,7 @@ See how to document them below, according to the state of the flag: - [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). -NOTE: **Note:** -The [`**(CORE ONLY)**`](styleguide.md#product-badges) badge or equivalent for +The [`**(CORE ONLY)**`](styleguide/index.md#product-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. diff --git a/doc/development/documentation/graphql_styleguide.md b/doc/development/documentation/graphql_styleguide.md index 11e6b159359..d658794f7e0 100644 --- a/doc/development/documentation/graphql_styleguide.md +++ b/doc/development/documentation/graphql_styleguide.md @@ -67,7 +67,7 @@ Set up the section with the following: ``` - Include a screenshot of the result in the GraphiQL explorer. Follow the naming - convention described in the [Save the image](styleguide.md#save-the-image) section of the Documentation style guide. + convention described in the [Save the image](styleguide/index.md#save-the-image) section of the Documentation style guide. - Follow up with an example of what you can do with the output. Make sure the example is something that readers can do on their own deployments. - Include a link to the [GraphQL API resources](../../api/graphql/reference/index.md). diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index e51f966ee6e..69a8ff10878 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -11,7 +11,7 @@ GitLab's documentation is [intended as the single source of truth (SSOT)](https: In addition to this page, the following resources can help you craft and contribute to documentation: -- [Style Guide](styleguide.md) - What belongs in the docs, language guidelines, Markdown standards to follow, links, and more. +- [Style Guide](styleguide/index.md) - What belongs in the docs, language guidelines, Markdown standards to follow, links, and more. - [Structure and template](structure.md) - Learn the typical parts of a doc page and how to write each one. - [Documentation process](workflow.md). - [Markdown Guide](../../user/markdown.md) - A reference for all Markdown syntax supported by GitLab. @@ -64,11 +64,11 @@ However, anyone can contribute [documentation improvements](workflow.md) that ar [GitLab docs](https://gitlab.com/gitlab-org/gitlab-docs) uses [GitLab Kramdown](https://gitlab.com/gitlab-org/gitlab_kramdown) as its Markdown rendering engine. See the [GitLab Markdown Guide](https://about.gitlab.com/handbook/markdown-guide/) for a complete Kramdown reference. -Adhere to the [Documentation Style Guide](styleguide.md). If a style standard is missing, you are welcome to suggest one via a merge request. +Adhere to the [Documentation Style Guide](styleguide/index.md). If a style standard is missing, you are welcome to suggest one via a merge request. ## Folder structure and files -See the [Structure](styleguide.md#structure) section of the [Documentation Style Guide](styleguide.md). +See the [Structure](styleguide/index.md#structure) section of the [Documentation Style Guide](styleguide/index.md). ## Metadata @@ -229,7 +229,7 @@ Things to note: it in for `workflow/lfs/lfs_administration` and `lfs/lfs_administration` and will print the file and the line where this file is mentioned. You may ask why the two greps. Since [we use relative paths to link to - documentation](styleguide.md#links), sometimes it might be useful to search a path deeper. + documentation](styleguide/index.md#links), sometimes it might be useful to search a path deeper. - The `*.md` extension is not used when a document is linked to GitLab's built-in help page, which is why we omit it in `git grep`. - Use the checklist on the "Change documentation location" MR description template. @@ -472,269 +472,7 @@ The following GitLab features are used among others: ## Testing -We treat documentation as code, and so use tests in our CI pipeline to maintain the -standards and quality of the docs. The current tests, which run in CI jobs when a -merge request with new or changed docs is submitted, are: - -- [`docs lint`](https://gitlab.com/gitlab-org/gitlab/-/blob/0b562014f7b71f98540e682c8d662275f0011f2f/.gitlab/ci/docs.gitlab-ci.yml#L41): - Runs several tests on the content of the docs themselves: - - [`lint-doc.sh` script](https://gitlab.com/gitlab-org/gitlab/blob/master/scripts/lint-doc.sh) - runs the following checks and linters: - - All cURL examples use the long flags (ex: `--header`, not `-H`). - - The `CHANGELOG.md` does not contain duplicate versions. - - No files in `doc/` are executable. - - No new `README.md` was added. - - [markdownlint](#markdownlint). - - [Vale](#vale). - - Nanoc tests: - - [`internal_links`](https://gitlab.com/gitlab-org/gitlab/-/blob/0b562014f7b71f98540e682c8d662275f0011f2f/.gitlab/ci/docs.gitlab-ci.yml#L58) - checks that all internal links (ex: `[link](../index.md)`) are valid. - - [`internal_anchors`](https://gitlab.com/gitlab-org/gitlab/-/blob/0b562014f7b71f98540e682c8d662275f0011f2f/.gitlab/ci/docs.gitlab-ci.yml#L60) - checks that all internal anchors (ex: `[link](../index.md#internal_anchor)`) - are valid. - - [`ui-docs-links lint`](https://gitlab.com/gitlab-org/gitlab/-/blob/0b562014f7b71f98540e682c8d662275f0011f2f/.gitlab/ci/docs.gitlab-ci.yml#L62) - checks that all links to docs from UI elements (`app/views` files, for example) - are linking to valid docs and anchors. - -### Run tests locally - -Apart from [previewing your changes locally](#previewing-the-changes-live), you can also run all lint checks -and Nanoc tests locally. - -#### Lint checks - -Lint checks are performed by the [`lint-doc.sh`](https://gitlab.com/gitlab-org/gitlab/blob/master/scripts/lint-doc.sh) -script and can be executed as follows: - -1. Navigate to the `gitlab` directory. -1. Run: - - ```shell - MD_DOC_PATH=path/to/my_doc.md scripts/lint-doc.sh - ``` - -Where `MD_DOC_PATH` points to the file or directory you would like to run lint checks for. -If you omit it completely, it will default to the `doc/` directory. -The output should be similar to: - -```plaintext -=> Linting documents at path /path/to/gitlab as <user>... -=> Checking for cURL short options... -=> Checking for CHANGELOG.md duplicate entries... -=> Checking /path/to/gitlab/doc for executable permissions... -=> Checking for new README.md files... -=> Linting markdown style... -=> Linting prose... -✔ 0 errors, 0 warnings and 0 suggestions in 1 file. -✔ Linting passed -``` - -Note that this requires you to either have the required lint tools installed on your machine, -or a working Docker installation, in which case an image with these tools pre-installed will be used. - -#### Nanoc tests - -To execute Nanoc tests locally: - -1. Navigate to the [`gitlab-docs`](https://gitlab.com/gitlab-org/gitlab-docs) directory. -1. Run: - - ```shell - # Check for broken internal links - bundle exec nanoc check internal_links - - # Check for broken external links (might take a lot of time to complete). - # This test is set to be allowed to fail and is run only in the gitlab-docs project CI - bundle exec nanoc check internal_anchors - ``` - -#### `ui-docs-links` test - -The `ui-docs-links lint` job uses `haml-lint` to test that all links to docs from -UI elements (`app/views` files, for example) are linking to valid docs and anchors. - -To run the `ui-docs-links` test locally: - -1. Open the `gitlab` directory in a terminal window. -1. Run: - - ```shell - bundle exec haml-lint -i DocumentationLinks - ``` - -If you receive an error the first time you run this test, run `bundle install`, which -installs GitLab's dependencies, and try again. - -If you don't want to install all of GitLab's dependencies to test the links, you can: - -1. Open the `gitlab` directory in a terminal window. -1. Install `haml-lint`: - - ```shell - gem install haml_lint - ``` - -1. Run: - - ```shell - haml-lint -i DocumentationLinks - ``` - -If you manually install `haml-lint` with this process, it will not update automatically -and you should make sure your version matches the version used by GitLab. - -### Local linters - -To help adhere to the [documentation style guidelines](styleguide.md), and improve the content -added to documentation, [install documentation linters](#install-linters) and -[integrate them with your code editor](#configure-editors). - -At GitLab, we mostly use: - -- [markdownlint](#markdownlint) -- [Vale](#vale) - -#### markdownlint - -[markdownlint](https://github.com/DavidAnson/markdownlint) checks that Markdown syntax follows -[certain rules](https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#rules), and is -used by the [`docs-lint` test](#testing). - -Our [Documentation Style Guide](styleguide.md#markdown) and -[Markdown Guide](https://about.gitlab.com/handbook/markdown-guide/) elaborate on which choices must -be made when selecting Markdown syntax for GitLab documentation. This tool helps catch deviations -from those guidelines. - -markdownlint configuration is found in the following projects: - -- [`gitlab`](https://gitlab.com/gitlab-org/gitlab/blob/master/.markdownlint.json) -- [`gitlab-runner`](https://gitlab.com/gitlab-org/gitlab-runner/blob/master/.markdownlint.json) -- [`omnibus-gitlab`](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/.markdownlint.json) -- [`charts`](https://gitlab.com/gitlab-org/charts/gitlab/-/blob/master/.markdownlint.json) -- [`gitlab-development-kit`](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/master/.markdownlint.json) - -This configuration is also used within build pipelines. - -You can use markdownlint: - -- [On the command line](https://github.com/igorshubovych/markdownlint-cli#markdownlint-cli--). -- [Within a code editor](#configure-editors). -- [In a `pre-commit` hook](#configure-pre-commit-hooks). - -#### Vale - -[Vale](https://errata-ai.gitbook.io/vale/) is a grammar, style, and word usage linter for the -English language. Vale's configuration is stored in the -[`.vale.ini`](https://gitlab.com/gitlab-org/gitlab/blob/master/.vale.ini) file located in the root -directory of projects. - -Vale supports creating [custom tests](https://errata-ai.github.io/vale/styles/) that extend any of -several types of checks, which we store in the `.linting/vale/styles/gitlab` directory within the -documentation directory of projects. - -Vale configuration is found in the following projects: - -- [`gitlab`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc/.vale/gitlab) -- [`gitlab-runner`](https://gitlab.com/gitlab-org/gitlab-runner/-/tree/master/docs/.vale/gitlab) -- [`omnibus-gitlab`](https://gitlab.com/gitlab-org/omnibus-gitlab/-/tree/master/doc/.vale/gitlab) -- [`charts`](https://gitlab.com/gitlab-org/charts/gitlab/-/tree/master/doc/.vale/gitlab) -- [`gitlab-development-kit`](https://gitlab.com/gitlab-org/gitlab-development-kit/-/tree/master/doc/.vale/gitlab) - -This configuration is also used within build pipelines. - -You can use Vale: - -- [On the command line](https://errata-ai.gitbook.io/vale/getting-started/usage). -- [Within a code editor](#configure-editors). -- [In a `pre-commit` hook](#configure-pre-commit-hooks). Vale only reports errors in the - `pre-commit` hook (the same configuration as the CI/CD pipelines), and does not report suggestions - or warnings. - -#### Install linters - -At a minimum, install [markdownlint](#markdownlint) and [Vale](#vale) to match the checks run in -build pipelines: - -1. Install `markdownlint-cli`, using either: - - - `npm`: - - ```shell - npm install -g markdownlint-cli - ``` - - - `yarn`: - - ```shell - yarn global add markdownlint-cli - ``` - - We recommend installing the version of `markdownlint-cli` currently used in the documentation - linting [Docker image](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/master/.gitlab-ci.yml#L420). - -1. Install [`vale`](https://github.com/errata-ai/vale/releases). For example, to install using - `brew` for macOS, run: - - ```shell - brew install vale - ``` - - We recommend installing the version of Vale currently used in the documentation linting - [Docker image](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/master/.gitlab-ci.yml#L419). - -In addition to using markdownlint and Vale at the command line, these tools can be -[integrated with your code editor](#configure-editors). - -#### Configure editors - -To configure markdownlint within your editor, install one of the following as appropriate: - -- [Sublime Text](https://packagecontrol.io/packages/SublimeLinter-contrib-markdownlint) -- [Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) -- [Atom](https://atom.io/packages/linter-node-markdownlint) -- [Vim](https://github.com/dense-analysis/ale) - -To configure Vale within your editor, install one of the following as appropriate: - -- The Sublime Text [`SublimeLinter-contrib-vale` plugin](https://packagecontrol.io/packages/SublimeLinter-contrib-vale). -- The Visual Studio Code [`errata-ai.vale-server` extension](https://marketplace.visualstudio.com/items?itemName=errata-ai.vale-server). You don't need Vale Server to use the plugin. -- [Vim](https://github.com/dense-analysis/ale). - -We don't use [Vale Server](https://errata-ai.github.io/vale/#using-vale-with-a-text-editor-or-another-third-party-application). - -#### Configure pre-commit hooks - -Git [pre-commit hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks) allow Git users to -run tests or other processes before committing to a branch, with the ability to not commit to the branch if -failures occur with these tests. - -[`overcommit`](https://github.com/sds/overcommit) is a Git hooks manager, making configuring, -installing, and removing Git hooks easy. - -Sample configuration for `overcommit` is available in the -[`.overcommit.yml.example`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.overcommit.yml.example) -file for the [`gitlab`](https://gitlab.com/gitlab-org/gitlab) project. - -To set up `overcommit` for documentation linting, see -[Pre-commit static analysis](../contributing/style_guides.md#pre-commit-static-analysis). - -#### Disable Vale tests - -You can disable a specific Vale linting rule or all Vale linting rules for any portion of a -document: - -- To disable a specific rule, add a `<!-- vale gitlab.rulename = NO -->` tag before the text, and a - `<!-- vale gitlab.rulename = YES -->` tag after the text, replacing `rulename` with the filename - of a test in the - [GitLab styles](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc/.linting/vale/styles/gitlab) - directory. -- To disable all Vale linting rules, add a `<!-- vale off -->` tag before the text, and a - `<!-- vale on -->` tag after the text. - -Whenever possible, exclude only the problematic rule and line(s). - -For more information, see -[Vale's documentation](https://errata-ai.gitbook.io/vale/getting-started/markup#markup-based-configuration). +For more information on documentation testing, see [Documentation testing](testing.md) ## Danger Bot diff --git a/doc/development/documentation/restful_api_styleguide.md b/doc/development/documentation/restful_api_styleguide.md index b12578b5d98..13c6140114f 100644 --- a/doc/development/documentation/restful_api_styleguide.md +++ b/doc/development/documentation/restful_api_styleguide.md @@ -38,12 +38,16 @@ The following can be used as a template to get started: ````markdown ## Descriptive title +> Version history note. + One or two sentence description of what endpoint does. ```plaintext METHOD /endpoint ``` +Supported attributes: + | Attribute | Type | Required | Description | |:------------|:---------|:---------|:----------------------| | `attribute` | datatype | yes/no | Detailed description. | @@ -65,6 +69,9 @@ Example response: ``` ```` +Adjust the [version history note accordingly](styleguide/index.md#version-text-in-the-version-history) +to describe the GitLab release that introduced the API call. + ## Method description Use the following table headers to describe the methods. Attributes should @@ -105,8 +112,8 @@ you can use in the API documentation. CAUTION: **Caution:** Do not use information for real users, URLs, or tokens. For documentation, refer to our -relevant style guide sections on [Fake user information](styleguide.md#fake-user-information), -[Fake URLs](styleguide.md#fake-urls), and [Fake tokens](styleguide.md#fake-tokens). +relevant style guide sections on [Fake user information](styleguide/index.md#fake-user-information), +[Fake URLs](styleguide/index.md#fake-urls), and [Fake tokens](styleguide/index.md#fake-tokens). ### Simple cURL command @@ -136,14 +143,26 @@ curl --data "name=foo" --header "PRIVATE-TOKEN: <your_access_token>" "https://gi ### Post data using JSON content -NOTE: **Note:** -In this example we create a new group. Watch carefully the single and double -quotes. +This example creates a new group. Be aware of the use of single (`'`) and double +(`"`) quotes. ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" --data '{"path": "my-group", "name": "My group"}' "https://gitlab.example.com/api/v4/groups" ``` +For readability, you can also set up the `--data` by using the following format: + +```shell +curl --request POST \ +--url "https://gitlab.example.com/api/v4/groups" \ +--header "content-type: application/json" \ +--header "PRIVATE-TOKEN: <your_access_token>" \ +--data '{ + "path": "my-group", + "name": "My group" +}' +``` + ### Post data using form-data Instead of using JSON or urlencode you can use multipart/form-data which diff --git a/doc/development/documentation/site_architecture/deployment_process.md b/doc/development/documentation/site_architecture/deployment_process.md index 00cdc69d422..f101a669968 100644 --- a/doc/development/documentation/site_architecture/deployment_process.md +++ b/doc/development/documentation/site_architecture/deployment_process.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Documentation deployment process The [`dockerfiles` directory](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/dockerfiles/) diff --git a/doc/development/documentation/site_architecture/global_nav.md b/doc/development/documentation/site_architecture/global_nav.md index 9fce9b4e4b3..21b0c4b6b43 100644 --- a/doc/development/documentation/site_architecture/global_nav.md +++ b/doc/development/documentation/site_architecture/global_nav.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers description: "Learn how GitLab docs' global navigation works and how to add new items." --- @@ -67,7 +70,6 @@ With these groups in mind, the following are general rules for where new items s - Other documentation belongs at the top-level, but care must be taken to not create an enormously long top-level navigation, which defeats the purpose of it. -NOTE: **Note:** Making all documentation and navigation items adhere to these principles is being progressively rolled out. @@ -114,7 +116,6 @@ for clarity. To see the improvements planned, check the [global nav epic](https://gitlab.com/groups/gitlab-com/-/epics/21). -NOTE: **Note:** **Do not** [add items](#adding-new-items) to the global nav without the consent of one of the technical writers. diff --git a/doc/development/documentation/site_architecture/index.md b/doc/development/documentation/site_architecture/index.md index 5d3af6721d1..3772746e25b 100644 --- a/doc/development/documentation/site_architecture/index.md +++ b/doc/development/documentation/site_architecture/index.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers description: "Learn how GitLab's documentation website is architectured." --- @@ -227,8 +230,9 @@ for its search function. This is how it works: there's a JavaScript snippet which initiates DocSearch by using an API key and an index name (`gitlab`) that are needed for Algolia to show the results. -NOTE: **For GitLab Team Members:** -If you’re a GitLab Team Member, find credentials for the Algolia dashboard +### Algolia notes for GitLab team members + +If you’re a GitLab team member, find credentials for the Algolia dashboard in the shared [GitLab 1Password account](https://about.gitlab.com/handbook/security/#1password-for-teams). To receive weekly reports of the search usage, search the Google doc with title `Email, Slack, and GitLab Groups and Aliases`, search for `docsearch`, diff --git a/doc/development/documentation/site_architecture/release_process.md b/doc/development/documentation/site_architecture/release_process.md index d04d34ff786..547adc89a08 100644 --- a/doc/development/documentation/site_architecture/release_process.md +++ b/doc/development/documentation/site_architecture/release_process.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # GitLab Docs monthly release process When a new GitLab version is released on the 22nd, we need to create the respective @@ -9,7 +15,6 @@ Since the charts use a different version number than all the other GitLab products, we need to add a [version mapping](https://docs.gitlab.com/charts/installation/version_mappings.html): -NOTE: **Note:** The charts stable branch is not created automatically like the other products. There's an [issue to track this](https://gitlab.com/gitlab-org/charts/gitlab/-/issues/1442). It is usually created on the 21st or the 22nd. @@ -158,7 +163,7 @@ Releasing a new version is a long process that involves many moving parts. ### `test_internal_links_and_anchors` failing on dropdown merge requests -NOTE: **Note:** +DANGER: **Deprecated:** We now pin versions in the `.gitlab-ci.yml` of the respective branch, so the steps below are deprecated. diff --git a/doc/development/documentation/structure.md b/doc/development/documentation/structure.md index e454a401a9d..3cc7f49f05e 100644 --- a/doc/development/documentation/structure.md +++ b/doc/development/documentation/structure.md @@ -10,7 +10,7 @@ description: What to include in GitLab documentation pages. Use these standards to contribute content to the GitLab documentation. Before getting started, familiarize yourself with [GitLab's Documentation guidelines](index.md) -and the [Documentation Style Guide](styleguide.md). +and the [Documentation Style Guide](styleguide/index.md). ## Components of a documentation page @@ -39,7 +39,7 @@ pre-deployment and post-deployment tasks. ## Template for new docs -Follow the [folder structure and file name guidelines](styleguide.md#folder-structure-overview) +Follow the [folder structure and file name guidelines](styleguide/index.md#folder-structure-overview) and create a new topic by using this template: ```markdown @@ -160,9 +160,9 @@ commented out to help encourage others to add to it in the future. --> Notes: -- (1): Apply the [tier badges](styleguide.md#product-badges) accordingly. +- (1): Apply the [tier badges](styleguide/index.md#product-badges) accordingly. - (2): Apply the correct format for the - [GitLab version that introduces the feature](styleguide.md#gitlab-versions-and-tiers). + [GitLab version that introduces the feature](styleguide/index.md#gitlab-versions-and-tiers). ``` ## Help and feedback section @@ -230,7 +230,6 @@ Consider the following guidelines when offering examples: - Better and best cases can be considered part of the good case(s) code block. In the same code block, precede each with comments: `# Better` and `# Best`. -NOTE: **Note:** Although the bad-then-good approach is acceptable for the GitLab development guidelines, do not use it for user documentation. For user documentation, use *Do* and *Don't*. For examples, see the [Pajamas Design System](https://design.gitlab.com/content/punctuation/). diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md index 6075124ef40..a12c2740083 100644 --- a/doc/development/documentation/styleguide.md +++ b/doc/development/documentation/styleguide.md @@ -1,2063 +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/#designated-technical-writers -description: 'Writing styles, markup, formatting, and other standards for GitLab Documentation.' +redirect_to: 'styleguide/index.md' --- -# Documentation Style Guide - -This document defines the standards for GitLab's documentation content and -files. - -For broader information about the documentation, see the [Documentation guidelines](index.md). - -For guidelines specific to text in the GitLab interface, see the Pajamas [Content](https://design.gitlab.com/content/error-messages) section. - -For information on how to validate styles locally or by using GitLab CI/CD, see [Testing](index.md#testing). - -Use this guide for standards on grammar, formatting, word usage, and more. - -You can also view a list of [recent updates to this guide](https://gitlab.com/dashboard/merge_requests?scope=all&utf8=%E2%9C%93&state=merged&label_name[]=tw-style¬[label_name][]=docs%3A%3Afix). - -If you can't find what you need: - -- View the GitLab Handbook for [writing style guidelines](https://about.gitlab.com/handbook/communication/#writing-style-guidelines) that apply to all GitLab content. -- Refer to one of the following: - - - [Microsoft Style Guide](https://docs.microsoft.com/en-us/style-guide/). - - [Google Developer Documentation Style Guide](https://developers.google.com/style). - -If you have questions about style, mention `@tw-style` in an issue or merge request, or, if you have access to the GitLab Slack workspace, use `#docs-process`. - -## Documentation is the single source of truth (SSOT) - -### Why a single source of truth - -The documentation of GitLab products and features is the SSOT for all -information related to implementation, usage, and troubleshooting. It evolves -continuously, in keeping with new products and features, and with improvements -for clarity, accuracy, and completeness. - -This policy prevents information silos, making it easier to find information -about GitLab products. - -It also informs decisions about the kinds of content we include in our -documentation. - -### All information - -Include problem-solving actions that may address rare cases or be considered -*risky*, so long as proper context is provided in the form of 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 -Technical Writing team. - -We will add all troubleshooting information to the documentation, no matter how -unlikely a user is to encounter a situation. For the [Troubleshooting sections](#troubleshooting), -people in GitLab Support can merge additions themselves. - -### All media types - -Include any media types/sources if the content is relevant to readers. You can -freely include or link presentations, diagrams, videos, and so on; no matter who -it was originally composed for, if it is helpful to any of our audiences, we can -include it. - -- If you use an image that has a separate source file (for example, a vector or - diagram format), link the image to the source file so that it may be reused or - updated by anyone. -- Do not copy and paste content from other sources unless it is a limited - quotation with the source cited. Typically it is better to either rephrase - relevant information in your own words or link out to the other source. - -### No special types - -In the software industry, it is a best practice to organize documentation in -different types. For example, [Divio recommends](https://www.divio.com/blog/documentation/): - -- Tutorials -- How-to guides -- Explanation -- Reference (for example, a glossary) - -At GitLab, we have so many product changes in our monthly releases that we can't -afford to continuously update multiple types of information. If we have multiple -types, the information will become outdated. Therefore, we have a -[single template](structure.md) for documentation. - -We currently do not distinguish specific document types, although we are open to -reconsidering this policy after the documentation has reached a future stage of -maturity and quality. If you are reading this, then despite our continuous -improvement efforts, that point hasn't been reached. - -### Link instead of summarize - -There is a temptation to summarize the information on another page. This will -cause the information to live in two places. Instead, link to the single source -of truth and explain why it is important to consume the information. - -### Organize by topic, not by type - -Beyond top-level audience-type folders (for example, `administration`), we -organize content by topic, not by type, so it can be located as easily as -possible within the single-source-of-truth (SSOT) section for the subject -matter. - -For example, do not create groupings of similar media types. For example: - -- Glossaries. -- FAQs. -- Sets of all articles or videos. - -Such grouping of content by type makes it difficult to browse for the information -you need and difficult to maintain up-to-date content. Instead, organize content -by its subject (for example, everything related to CI goes together) and -cross-link between any related content. - -### Docs-first methodology - -We employ a *documentation-first methodology* to help ensure the documentation -remains a complete and trusted resource, and to make communicating about the use -of GitLab more efficient. - -- If the answer to a question exists in documentation, share the link to the - documentation instead of rephrasing the information. -- When you encounter new information not available in GitLab’s documentation (for - example, when working on a support case or testing a feature), your first step - should be to create a merge request (MR) to add this information to the - documentation. You can then share the MR in order to communicate this - information. - -New information that would be useful toward the future usage or troubleshooting -of GitLab should not be written directly in a forum or other messaging system, -but added to a documentation MR and then referenced, as described above. Note -that among any other documentation changes, you can either: - -- Add a [Troubleshooting section](#troubleshooting) to a doc if none exists. -- Un-comment and use the placeholder Troubleshooting section included as part of - our [documentation template](structure.md#template-for-new-docs), if present. - -The more we reflexively add useful information to the documentation, the more -(and more successfully) the documentation will be used to efficiently accomplish -tasks and solve problems. - -If you have questions when considering, authoring, or editing documentation, ask -the Technical Writing team on Slack in `#docs` or in GitLab by mentioning the -writer for the applicable [DevOps stage](https://about.gitlab.com/handbook/product/product-categories/#devops-stages). -Otherwise, forge ahead with your best effort. It does not need to be perfect; -the team is happy to review and improve upon your content. Please review the -[Documentation guidelines](index.md) before you begin your first documentation MR. - -Having a knowledge base in any form that is separate from the documentation would -be against the documentation-first methodology because the content would overlap with -the documentation. - -## Markdown - -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 -will support all [GFM markup](../../user/markdown.md) in the future. That is, -all markup supported for display in the GitLab application itself. For now, use -regular Markdown markup, following the rules in the linked style guide. - -Note that Kramdown-specific markup (for example, `{:.class}`) will not render -properly on GitLab instances under [`/help`](index.md#gitlab-help). - -### HTML in Markdown - -Hard-coded HTML is valid, although it's discouraged from being used while we -have `/help`. HTML is permitted as long as: - -- There's no equivalent markup in Markdown. -- Advanced tables are necessary. -- Special styling is required. -- Reviewed and approved by a technical writer. - -### Markdown Rules - -GitLab ensures that the Markdown used across all documentation is consistent, as -well as easy to review and maintain, by [testing documentation changes](index.md#testing) -with [markdownlint](index.md#markdownlint). This lint test fails when any -document has an issue with Markdown formatting that may cause the page to render -incorrectly within GitLab. It will also fail when a document is using -non-standard Markdown (which may render correctly, but is not the current -standard for GitLab documentation). - -#### Markdown rule `MD044/proper-names` (capitalization) - -A rule that could cause confusion is `MD044/proper-names`, as it might not be -immediately clear what caused markdownlint to fail, or how to correct the -failure. This rule checks a list of known words, listed in the `.markdownlint.json` -file in each project, to verify proper use of capitalization and backticks. -Words in backticks will be ignored by markdownlint. - -In general, product names should follow the exact capitalization of the official -names of the products, protocols, and so on. See [`.markdownlint.json`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.markdownlint.json) -for the words tested for proper capitalization in GitLab documentation. - -Some examples fail if incorrect capitalization is used: - -- MinIO (needs capital `IO`) -- NGINX (needs all capitals) -- runit (needs lowercase `r`) - -Additionally, commands, parameters, values, filenames, and so on must be -included in backticks. For example: - -- "Change the `needs` keyword in your `.gitlab.yml`..." - - `needs` is a parameter, and `.gitlab.yml` is a file, so both need backticks. - Additionally, `.gitlab.yml` will fail markdownlint without backticks as it - does not have capital G or L. -- "Run `git clone` to clone a Git repository..." - - `git clone` is a command, so it must be lowercase, while Git is the product, - so it must have a capital G. - -## Structure - -Because we want documentation to be a SSOT, we should [organize by topic, not by -type](#organize-by-topic-not-by-type). - -### Folder structure overview - -The documentation is separated by top-level audience folders [`user`](https://gitlab.com/gitlab-org/gitlab-foss/tree/master/doc/user), -[`administration`](https://gitlab.com/gitlab-org/gitlab-foss/tree/master/doc/administration), -and [`development`](https://gitlab.com/gitlab-org/gitlab-foss/tree/master/doc/development) -(contributing) folders. - -Beyond that, we primarily follow the structure of the GitLab user interface or -API. - -Our goal is to have a clear hierarchical structure with meaningful URLs like -`docs.gitlab.com/user/project/merge_requests/`. With this pattern, you can -immediately tell that you are navigating to user-related documentation about -Project features; specifically about Merge Requests. Our site's paths match -those of our repository, so the clear structure also makes documentation easier to update. - -The table below shows what kind of documentation goes where. - -| Directory | What belongs here | -|:----------------------|:----------------------------------------------------------------------------------------------------------------------------------------| -| `doc/user/` | User related documentation. Anything that can be done within the GitLab user interface goes here, including usage of the `/admin` interface. | -| `doc/administration/` | Documentation that requires the user to have access to the server where GitLab is installed. The admin settings that can be accessed via GitLab's interface exist under `doc/user/admin_area/`. | -| `doc/api/` | API related documentation. | -| `doc/development/` | Documentation related to the development of GitLab, whether contributing code or documentation. Related process and style guides should go here. | -| `doc/legal/` | Legal documents about contributing to GitLab. | -| `doc/install/` | Contains instructions for installing GitLab. | -| `doc/update/` | Contains instructions for updating GitLab. | -| `doc/topics/` | Indexes per topic (`doc/topics/topic_name/index.md`): all resources for that topic. | - -### Work with directories and files - -1. When you create a new directory, always start with an `index.md` file. - Do not use another file name 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, - proper naming would be `import_project/import_from_github.md`. This applies - to both image files and Markdown files. -1. For image files, do not exceed 100KB. -1. Do not upload video files to the product repositories. - [Link or embed videos](#videos) instead. -1. There are four main directories: `user`, `administration`, `api`, and - `development`. -1. The `doc/user/` directory has five main subdirectories: `project/`, `group/`, - `profile/`, `dashboard/` and `admin_area/`. - 1. `doc/user/project/` should contain all project related documentation. - 1. `doc/user/group/` should contain all group related documentation. - 1. `doc/user/profile/` should contain all profile related documentation. - Every page you would navigate under `/profile` should have its own document, - for example, `account.md`, `applications.md`, or `emails.md`. - 1. `doc/user/dashboard/` should contain all dashboard related documentation. - 1. `doc/user/admin_area/` should contain all admin related documentation - describing what can be achieved by accessing GitLab's admin interface - (_not to be confused with `doc/administration` where server access is - required_). - 1. Every category under `/admin/application_settings/` should have its - own document located at `doc/user/admin_area/settings/`. For example, - the **Visibility and Access Controls** category should have a document - located at `doc/user/admin_area/settings/visibility_and_access_controls.md`. -1. The `doc/topics/` directory holds topic-related technical content. Create - `doc/topics/topic_name/subtopic_name/index.md` when subtopics become necessary. - General user- and admin- related documentation, should be placed accordingly. -1. The `/university/` directory is *deprecated* and the majority of its documentation - has been moved. - -If you are unsure where to place a document or a content addition, this should -not stop you from authoring and contributing. You can use your best judgment and -then ask the reviewer of your MR to confirm your decision, and/or ask a -technical writer at any stage in the process. The technical writing team will -review all documentation changes, regardless, and can move content if there is a -better place for it. - -### Avoid duplication - -Do not include the same information in multiple places. -[Link to a single source of truth instead.](#link-instead-of-summarize) - -### References across documents - -- Give each folder an `index.md` page that introduces the topic, introduces the - pages within, and links to the pages within (including to the index pages of - any next-level subpaths). -- To ensure discoverability, ensure each new or renamed doc is linked from its - higher-level index page and other related pages. -- When making reference to other GitLab products and features, link to their - respective documentation, at least on first mention. -- When making reference to third-party products or technologies, link out to - their external sites, documentation, and resources. - -### Structure within documents - -- Include any and all applicable subsections as described on the - [structure and template](structure.md) page. -- Structure content in alphabetical order in tables, lists, and so on, unless - there's a logical reason not to (for example, when mirroring the user - interface or an otherwise ordered sequence). - -## Language - -GitLab documentation should be clear and easy to understand. - -- Be clear, concise, and stick to the goal of the documentation. -- Write in US English with US grammar. (Tested in [`British.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/British.yml).) -- Use [inclusive language](#inclusive-language). - -### Point of view - -In most cases, it’s appropriate to use the second-person (you, yours) point of -view, because it’s friendly and easy to understand. (Tested in -[`FirstPerson.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/FirstPerson.yml).) - -<!-- How do we harmonize the second person in Pajamas with our first person plural in our doc guide? --> - -### Capitalization - -#### Headings - -Use sentence case. For example: - -- `# Use variables to configure pipelines` -- `## Use the To-Do List` - -#### UI text - -When referring to specific user interface text, like a button label or menu -item, use the same capitalization that is 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 is called for in this Documentation Style Guide. - -If you think there is a mistake in the way the user interface text is styled, -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, to dos -- *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. - -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) -by default. - -#### Other terms - -Capitalize names of: - -- GitLab [product tiers](https://about.gitlab.com/pricing/). For example, - GitLab Core and GitLab Ultimate. (Tested in [`BadgeCapitalization.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/BadgeCapitalization.yml).) -- Third-party organizations, software, and products. For example, Prometheus, - Kubernetes, Git, and The Linux Foundation. -- Methods or methodologies. For example, Continuous Integration, - Continuous Deployment, Scrum, and Agile. (Tested in [`.markdownlint.json`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.markdownlint.json).) - -Follow the capitalization style listed at the [authoritative source](#links-to-external-documentation) -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**. - -### Inclusive language - -We strive to create documentation that is inclusive. This section includes -guidance and examples in the following categories: - -- [Gender-specific wording](#avoid-gender-specific-wording). - (Tested in [`InclusionGender.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionGender.yml).) -- [Ableist language](#avoid-ableist-language). - (Tested in [`InclusionAbleism.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionAbleism.yml).) -- [Cultural sensitivity](#culturally-sensitive-language). - (Tested in [`InclusionCultural.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionCultural.yml).) - -We write our developer documentation with inclusivity and diversity in mind. This -page is not an exhaustive reference, but describes some general guidelines and -examples that illustrate some best practices to follow. - -#### Avoid gender-specific wording - -When possible, use gender-neutral pronouns. For example, you can use a singular -[they](https://developers.google.com/style/pronouns#gender-neutral-pronouns) as -a gender-neutral pronoun. - -Avoid the use of gender-specific pronouns, unless referring to a specific person. - -<!-- vale gitlab.InclusionGender = NO --> - -| Use | Avoid | -|-----------------------------------|---------------------------------| -| People, humanity | Mankind | -| GitLab Team Members | Manpower | -| You can install; They can install | He can install; She can install | - -<!-- vale gitlab.InclusionGender = YES --> - -If you need to set up [Fake user information](#fake-user-information), use -diverse or non-gendered names with common surnames. - -#### Avoid ableist language - -Avoid terms that are also used in negative stereotypes for different groups. - -<!-- vale gitlab.InclusionAbleism = NO --> - -| Use | Avoid | -|------------------------|----------------------| -| Check for completeness | Sanity check | -| Uncertain outliers | Crazy outliers | -| Slows the service | Cripples the service | -| Placeholder variable | Dummy variable | -| Active/Inactive | Enabled/Disabled | -| On/Off | Enabled/Disabled | - -<!-- vale gitlab.InclusionAbleism = YES --> - -Credit: [Avoid ableist language](https://developers.google.com/style/inclusive-documentation#ableist-language) -in the Google Developer Style Guide. - -#### Culturally sensitive language - -Avoid terms that reflect negative cultural stereotypes and history. In most -cases, you can replace terms such as `master` and `slave` with terms that are -more precise and functional, such as `primary` and `secondary`. - -<!-- vale gitlab.InclusionCultural = NO --> - -| Use | Avoid | -|----------------------|-----------------------| -| Primary / secondary | Master / slave | -| Allowlist / denylist | Blacklist / whitelist | - -<!-- vale gitlab.InclusionCultural = YES --> - -For more information see the following [Internet Draft specification](https://tools.ietf.org/html/draft-knodel-terminology-02). - -### 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: - -- **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`. - -### Fake URLs - -When including sample URLs in the documentation, use: - -- `example.com` when the domain name is generic. -- `gitlab.example.com` when referring to self-managed instances of GitLab. - -### Fake tokens - -There may be times where a token is needed to demonstrate an API call using -cURL or a variable used in CI. It is strongly advised not to use real tokens in -documentation even if the probability of a token being exploited is low. - -You can use the following fake tokens as examples: - -| Token type | Token value | -|:----------------------|:-------------------------------------------------------------------| -| Private user token | `<your_access_token>` | -| Personal access token | `n671WNGecHugsdEDPsyo` | -| Application ID | `2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6` | -| Application secret | `04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df` | -| CI/CD variable | `Li8j-mLUVA3eZYjPfd_H` | -| Specific runner token | `yrnZW46BrtBFqM7xDzE7dddd` | -| Shared runner token | `6Vk7ZsosqQyfreAxXTZr` | -| Trigger token | `be20d8dcc028677c931e04f3871a9b` | -| Webhook secret token | `6XhDroRcYPM5by_h-HLY` | -| Health check token | `Tu7BgjR9qeZTEyRzGG2P` | -| Request profile token | `7VgpS4Ax5utVD2esNstz` | - -### Language to avoid - -When creating documentation, limit or avoid the use of the following verb -tenses, words, and phrases: - -- Avoid jargon when possible, and when not possible, define the term or - [link to a definition](#links-to-external-documentation). -- Avoid uncommon words when a more-common alternative is possible, ensuring that - content is accessible to more readers. -- Don't write in the first person singular. - (Tested in [`FirstPerson.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/FirstPerson.yml).) - - Instead of "I" or "me," use "we," "you," "us," or "one." - - When possible, stay user focused by writing in the second person ("you" or - the imperative). -- Don't overuse "that". In many cases, you can remove "that" from a sentence - and improve readability. -- Avoid use of the future tense: - - Instead of "after you execute this command, GitLab will display the - result", use "after you execute this command, GitLab displays the result". - - Only use the future tense to convey when the action or result will actually - occur at a future time. -- Don't use slashes to clump different words together or as a replacement for - the word "or": - - Instead of "and/or," consider using "or," or use another sensible - construction. - - Other examples include "clone/fetch," author/assignee," and - "namespace/repository name." Break apart any such instances in an - appropriate way. - - Exceptions to this rule include commonly accepted technical terms, such as - CI/CD and TCP/IP. -- <!-- vale gitlab.LatinTerms = NO --> - We discourage use of Latin abbreviations, such as "e.g.," "i.e.," or "etc.," - as even native users of English might misunderstand them. - (Tested in [`LatinTerms.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/LatinTerms.yml).) - - Instead of "i.e.," use "that is." - - Instead of "e.g.," use "for example," "such as," "for instance," or "like." - - Instead of "etc.," either use "and so on" or consider editing it out, since - it can be vague. - <!-- vale gitlab.LatinTerms = YES --> -- Avoid using the word *currently* when talking about the product or its - features. The documentation describes the product as it is, and not as it - will be at some indeterminate point in the future. -- Avoid the using the word *scalability* with increasing GitLab's performance - for additional users. Using the words *scale* or *scaling* in other cases is - acceptable, but references to increasing GitLab's performance for additional - users should direct readers to the GitLab - [reference architectures](../../administration/reference_architectures/index.md) - page. -- Avoid all forms of the phrases *high availability* and *HA*, and instead - direct readers to the GitLab [reference architectures](../../administration/reference_architectures/index.md) - for information about configuring GitLab to have the performance needed for - additional users over time. -- Don't use profanity or obscenities. Doing so may negatively affect other - users and contributors, which is contrary to GitLab's value of - [Diversity, Inclusion, and Belonging](https://about.gitlab.com/handbook/values/#diversity-inclusion). -- Avoid the use of [racially-insensitive terminology or phrases](https://www.marketplace.org/2020/06/17/tech-companies-update-language-to-avoid-offensive-terms/). For example: - - Use *primary* and *secondary* for database and server relationships. - - Use *allowlist* and *denylist* to describe access control lists. -- Avoid the word *please*. For details, see [the Microsoft style guide](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/p/please). - -### Word usage clarifications - -- Don't use "may" and "might" interchangeably: - - Use "might" to indicate the probability of something occurring. "If you - skip this step, the import process might fail." - - Use "may" to indicate giving permission for someone to do something, or - consider using "can" instead. "You may select either option on this - screen." Or, "You can select either option on this screen." - -### Contractions - -Contractions are encouraged, and can create a friendly and informal tone, -especially in tutorials, instructional documentation, and -[user interfaces](https://design.gitlab.com/content/punctuation/#contractions). - -Some contractions, however, should be avoided: - -- Do not use contractions with a proper noun and a verb. For example: - - | Do | Don't | - |------------------------------------------|-----------------------------------------| - | GitLab is creating X. | GitLab's creating X. | - -- Do not use contractions when you need to emphasize a negative. For example: - - | Do | Don't | - |------------------------------------------|-----------------------------------------| - | Do *not* install X with Y. | *Don't* install X with Y. | - -- Do not use contractions in reference documentation. For example: - - | Do | Don't | - |------------------------------------------|-----------------------------------------| - | Do *not* set a limit greater than 1000. | *Don't* set a limit greater than 1000. | - | For `parameter1`, the default is 10. | For `parameter1`, the default's 10. | - -- Avoid contractions in error messages. Examples: - - | Do | Don't | - |------------------------------------------|-----------------------------------------| - | Requests to localhost are not allowed. | Requests to localhost aren't allowed. | - | Specified URL cannot be used. | Specified URL can't be used. | - -## Text - -- [Write in Markdown](#markdown). -- Splitting long lines (preferably up to 100 characters) can make it easier to - provide feedback on small chunks of text. -- Insert an empty line for new paragraphs. -- Insert an empty line between different markups (for example, after every - paragraph, header, list, and so on). Example: - - ```markdown - ## Header - - Paragraph. - - - List item 1 - - List item 2 - ``` - -### Emphasis - -- Use double asterisks (`**`) to mark a word or text in bold (`**bold**`). -- Use underscore (`_`) for text in italics (`_italic_`). -- Use greater than (`>`) for blockquotes. - -### Punctuation - -Review the general punctuation rules for the GitLab documentation in the -following table. Check specific punctuation rules for [lists](#lists) below. -Additional examples are available in the [Pajamas guide for punctuation](https://design.gitlab.com/content/punctuation/). - -| Rule | Example | -|------------------------------------------------------------------|--------------------------------------------------------| -| 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' in a list. (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._ | -| Always use lowercase after a colon. | _Related Issues: a way to create a relationship between issues._ | - -### Placeholder text - -Often in examples, a writer will provide a command or configuration that -uses values specific to the reader. - -In these cases, use [`<` and `>`](https://en.wikipedia.org/wiki/Usage_message#Pattern) -to call out where a reader must replace text with their own value. - -For example: - -```shell -cp <your_source_directory> <your_destination_directory> -``` - -### Keyboard commands - -Use the HTML `<kbd>` tag when referring to keystroke presses. For example: - -```plaintext -To stop the command, press <kbd>Ctrl</kbd>+<kbd>C</kbd>. -``` - -When the docs are generated, the output is: - -To stop the command, press <kbd>Ctrl</kbd>+<kbd>C</kbd>. - -## Lists - -- Always start list items with a capital letter, unless they are parameters or - commands that are in backticks, or similar. -- Always leave a blank line before and after a list. -- Begin a line with spaces (not tabs) to denote a [nested sub-item](#nesting-inside-a-list-item). - -### Ordered vs. unordered lists - -Only use ordered lists when their items describe a sequence of steps to follow. - -Do: - -```markdown -These are the steps to do something: - -1. First, do the first step. -1. Then, do the next step. -1. Finally, do the last step. -``` - -Don't: - -```markdown -This is a list of available features: - -1. Feature 1 -1. Feature 2 -1. Feature 3 -``` - -### Markup - -- Use dashes (`-`) for unordered lists instead of asterisks (`*`). -- Prefix `1.` to every item in an ordered list. When rendered, the list items - will appear with sequential numbering automatically. - -### Punctuation - -- Do not add commas (`,`) or semicolons (`;`) to the end of list items. -- Only add periods to the end of a list item if the item consists of a complete - sentence. The [definition of full sentence](https://www2.le.ac.uk/offices/ld/all-resources/writing/grammar/grammar-guides/sentence) - is: _"a complete sentence always contains a verb, expresses a complete idea, and makes sense standing alone"_. -- Be consistent throughout the list: if the majority of the items do not end in - a period, do not end any of the items in a period, even if they consist of a - complete sentence. The opposite is also valid: if the majority of the items - end with a period, end all with a period. -- Separate list items from explanatory text with a colon (`:`). For example: - - ```markdown - The list is as follows: - - - First item: this explains the first item. - - Second item: this explains the second item. - ``` - -**Examples:** - -Do: - -- First list item -- Second list item -- Third list item - -Don't: - -- First list item -- Second list item -- Third list item. - -Do: - -- Let's say this is a complete sentence. -- Let's say this is also a complete sentence. -- Not a complete sentence. - -Don't (vary use of periods; majority rules): - -- Let's say this is a complete sentence. -- Let's say this is also a complete sentence. -- Not a complete sentence - -### Nesting inside a list item - -It's possible to nest items under a list item, so that they render with the same -indentation as the list item. This can be done with: - -- [Code blocks](#code-blocks) -- [Blockquotes](#blockquotes) -- [Alert boxes](#alert-boxes) -- [Images](#images) - -Items nested in lists should always align with the first character of the list -item. In unordered lists (using `-`), this means two spaces for each level of -indentation: - -````markdown -- Unordered list item 1 - - A line nested using 2 spaces to align with the `U` above. - -- Unordered list item 2 - - > A quote block that will nest - > inside list item 2. - -- Unordered list item 3 - - ```plaintext - a codeblock that will next inside list item 3 - ``` - -- Unordered list item 4 - - ![an image that will nest inside list item 4](image.png) -```` - -For ordered lists, use three spaces for each level of indentation: - -````markdown -1. Ordered list item 1 - - A line nested using 3 spaces to align with the `O` above. - -1. Ordered list item 2 - - > A quote block that will nest - > inside list item 2. - -1. Ordered list item 3 - - ```plaintext - a codeblock that will next inside list item 3 - ``` - -1. Ordered list item 4 - - ![an image that will nest inside list item 4](image.png) -```` - -You can nest full lists inside other lists using the same rules as above. If you -want to mix types, that is also possible, as long as you don't mix items at the -same level: - -```markdown -1. Ordered list item one. -1. Ordered list item two. - - Nested unordered list item one. - - Nested unordered list item two. -1. Ordered list item three. - -- Unordered list item one. -- Unordered list item two. - 1. Nested ordered list item one. - 1. Nested ordered list item two. -- Unordered list item three. -``` - -## Tables - -Tables should be used to describe complex information in a straightforward -manner. Note that in many cases, an unordered list is sufficient to describe a -list of items with a single, simple description per item. But, if you have data -that is best described by a matrix, tables are the best choice for use. - -### Creation guidelines - -Due to accessibility and scannability requirements, tables should not have any -empty cells. If there is no otherwise meaningful value for a cell, consider entering -*N/A* (for 'not applicable') or *none*. - -To help tables be easier to maintain, consider adding additional spaces to the -column widths to make them consistent. For example: - -```markdown -| App name | Description | Requirements | -|:---------|:---------------------|:---------------| -| App 1 | Description text 1. | Requirements 1 | -| App 2 | Description text 2. | None | -``` - -Consider installing a plugin or extension in your editor for formatting tables: - -- [Markdown Table Prettifier](https://marketplace.visualstudio.com/items?itemName=darkriszty.markdown-table-prettify) for Visual Studio Code -- [Markdown Table Formatter](https://packagecontrol.io/packages/Markdown%20Table%20Formatter) for Sublime Text -- [Markdown Table Formatter](https://atom.io/packages/markdown-table-formatter) for Atom - -### Feature tables - -When creating tables of lists of features (such as whether or not features are -available to certain roles on the [Permissions](../../user/permissions.md#project-members-permissions) -page), use the following phrases (based on the SVG icons): - -| Option | Markdown | Displayed result | -|--------|--------------------------|------------------------| -| No | `**{dotted-circle}** No` | **{dotted-circle}** No | -| Yes | `**{check-circle}** Yes` | **{check-circle}** Yes | - -## Quotes - -Valid for Markdown content only, not for front matter entries: - -- Standard quotes: double quotes (`"`). Example: "This is wrapped in double - quotes". -- Quote within a quote: double quotes (`"`) wrap single quotes (`'`). Example: - "I am 'quoting' something within a quote". - -For other punctuation rules, please refer to the -[GitLab UX guide](https://design.gitlab.com/content/punctuation/). - -## Headings - -- Add **only one H1** in each document, by adding `#` at the beginning of - it (when using Markdown). The `h1` will be 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` -- Avoid putting numbers in headings. Numbers shift, hence documentation anchor - links shift too, which eventually leads to dead links. If you think it is - compelling to add numbers in headings, make sure to at least discuss it with - someone in the Merge Request. -- [Avoid using symbols and special characters](https://gitlab.com/gitlab-org/gitlab-docs/-/issues/84) - in headers. Whenever possible, they should be plain and short text. -- When possible, avoid including words that might change in the future. Changing - a heading changes its anchor URL, which affects other linked pages. -- When introducing a new document, be careful for the headings to be - grammatically and syntactically correct. Mention an [assigned technical writer (TW)](https://about.gitlab.com/handbook/product/product-categories/) - for review. - This is to ensure that no document with wrong heading is going live without an - audit, thus preventing dead links and redirection issues when corrected. -- Leave exactly one blank line before and after a heading. -- Do not use links in headings. -- Add the corresponding [product badge](#product-badges) according to the tier the - feature belongs. -- Our documentation site search engine prioritizes words used in headings and - subheadings. Make you subheading titles clear, descriptive, and complete to help - users find the right example, as shown in the section on [heading titles](#heading-titles). -- See [Capitalization](#capitalization) for guidelines on capitalizing headings. - -### Heading titles - -Keep heading titles clear and direct. Make every word count. To accommodate -search engine optimization (SEO), use the imperative, where possible. - -| Do | Don't | -|:--------------------------------------|:------------------------------------------------------------| -| Configure GDK | Configuring GDK | -| GitLab Release and Maintenance Policy | This section covers GitLab's Release and Maintenance Policy | -| Backport to older releases | Backporting to older releases | -| GitLab Pages examples | Examples | - -For guidelines on capitalizing headings, see the section on [capitalization](#capitalization). - -NOTE: **Note:** -If you change an existing title, be careful. These changes might affect not -only [links](#anchor-links) within the page, but might also affect links to the -GitLab documentation from both the GitLab application and external sites. - -### Anchor links - -Headings generate anchor links automatically when rendered. `## This is an example` -generates the anchor `#this-is-an-example`. - -NOTE: **Note:** -[Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/39717) in GitLab 13.4, [product badges](#product-badges) used in headings aren't included in the -generated anchor links. For example, when you link to -`## This is an example **(CORE)**`, use the anchor `#this-is-an-example`. - -Keep in mind that the GitLab user interface links to many documentation pages -and anchor links to take the user to the right spot. Therefore, when you change -a heading, search `doc/*`, `app/views/*`, and `ee/app/views/*` for the old -anchor to make sure you're not breaking an anchor linked from other -documentation nor from the GitLab user interface. If you find the old anchor, be -sure to replace it with the new one. - -Important: - -- Avoid crosslinking documentation to headings unless you need to link to a - specific section of the document. This will avoid breaking anchors in the - future in case the heading is changed. -- If possible, avoid changing headings since they're not only linked internally. - There are various links to GitLab documentation on the internet, such as - tutorials, presentations, StackOverflow posts, and other sources. -- Do not link to `h1` headings. - -Note that, with Kramdown, it is possible to add a custom ID to an HTML element -with Markdown markup, but they **do not** work in GitLab's `/help`. Therefore, -do not use this option until further notice. - -## Links - -Links are important in GitLab documentation. They allow you to [link instead of -summarizing](#link-instead-of-summarize) to help preserve a [single source of truth](#why-a-single-source-of-truth) -within GitLab documentation. - -We include guidance for links in the following categories: - -- How to set up [anchor links](#anchor-links) for headings. -- How to set up [criteria](#basic-link-criteria) for configuring a link. -- What to set up when [linking to a `help`](../documentation/index.md#linking-to-help) - page. -- How to set up [links to internal documentation](#links-to-internal-documentation) - for cross-references. -- How to set up [links to external documentation](#links-to-external-documentation) - for authoritative sources. -- When to use [links requiring permissions](#links-requiring-permissions). -- How to set up a [link to a video](#link-to-video). -- How to [include links with version text](#text-for-documentation-requiring-version-text). -- How to [link to specific lines of code](#link-to-specific-lines-of-code) - -### Basic link criteria - -- Use inline link Markdown markup `[Text](https://example.com)`. - It's easier to read, review, and maintain. *Do not* use `[Text][identifier]`. - -- 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)`. - -### Links to internal documentation - -NOTE: **Note:** -_Internal_ refers to documentation in the same project. When linking to -documentation in separate projects (for example, linking to Omnibus documentation -from GitLab documentation), you must use absolute URLs. - -Do not use absolute URLs like `https://docs.gitlab.com/ee/index.html` to -crosslink to other documentation within the same project. Use relative links to -the file, like `../index.md`. (These are converted to HTML when the site is -rendered.) - -Relative linking enables crosslinks to work: - -- in Review Apps, local previews, and `/help`. -- when working on the documentation locally, so you can verify that they work as - early as possible in the process. -- within the GitLab user interface when browsing doc files in their respective - repositories. For example, the links displayed at - `https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/README.md`. - -To link to internal documentation: - -- Use relative links to Markdown files in the same repository. -- Do not use absolute URLs or URLs from `docs.gitlab.com`. -- Use `../` to navigate to higher-level directories. -- Do not link relative to root. For example, `/ee/user/gitlab_com/index.md`. - - Don't: - - - `https://docs.gitlab.com/ee/administration/geo/replication/troubleshooting.html` - - `/ee/administration/geo/replication/troubleshooting.md` - - Do: `../../geo/replication/troubleshooting.md` - -- Always add the file name `file.md` at the end of the link with the `.md` - extension, not `.html`. - - Don't: - - - `../../merge_requests/` - - `../../issues/tags.html` - - `../../issues/tags.html#stages` - - Do: - - - `../../merge_requests/index.md` - - `../../issues/tags.md` - - `../../issues/tags.md#stages` - -NOTE: **Note:** -Using the Markdown extension is necessary for the [`/help`](index.md#gitlab-help) -section of GitLab. - -### Links to external documentation - -When describing interactions with external software, it's often helpful to -include links to external documentation. When possible, make sure that you're -linking to an [**authoritative** source](#authoritative-sources). For example, -if you're describing a feature in Microsoft's Active Directory, include a link -to official Microsoft documentation. - -### Authoritative sources - -When citing external information, use sources that are written by the people who -created the item or product in question. These sources are the most likely to be -accurate and remain up to date. - -Examples of authoritative sources include: - -- Specifications, such as a [Request for Comments](https://www.ietf.org/standards/rfcs/) - document from the Internet Engineering Task Force. -- Official documentation for a product. For example, if you're setting up an - interface with the Google OAuth 2 authorization server, include a link to - Google's documentation. -- Official documentation for a project. For example, if you're citing NodeJS - functionality, refer directly to [NodeJS documentation](https://nodejs.org/en/docs/). -- Books from an authoritative publisher. - -Examples of sources to avoid include: - -- Personal blog posts. -- Wikipedia. -- Non-trustworthy articles. -- Discussions on forums such as Stack Overflow. -- Documentation from a company that describes another company's product. - -While many of these sources to avoid can help you learn skills and or features, -they can become obsolete quickly. Nobody is obliged to maintain any of these -sites. Therefore, we should avoid using them as reference literature. - -NOTE: **Note:** -Non-authoritative sources are acceptable only if there is no equivalent -authoritative source. Even then, focus on non-authoritative sources that are -extensively cited or peer-reviewed. - -### Links requiring permissions - -Don't link directly to: - -- [Confidential issues](../../user/project/issues/confidential_issues.md). -- Project features that require [special permissions](../../user/permissions.md) - to view. - -These will fail for: - -- Those without sufficient permissions. -- Automated link checkers. - -Instead: - -- To reduce confusion, mention in the text that the information is either: - - Contained in a confidential issue. - - Requires special permission to a project to view. -- Provide a link in back ticks (`` ` ``) so that those with access to the issue - can easily navigate to it. - -Example: - -```markdown -For more information, see the [confidential issue](../../user/project/issues/confidential_issues.md) `https://gitlab.com/gitlab-org/gitlab-foss/-/issues/<issue_number>`. -``` - -### Link to specific lines of code - -When linking to specific lines within a file, link to a commit instead of to the -branch. Lines of code change through time, therefore, linking to a line by using -the commit link ensures the user lands on the line you're referring to. The -**Permalink** button, which is available when viewing a file within a project, -makes it easy to generate a link to the most recent commit of the given 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).` - -If that linked expression is no longer in that line of the file due to additional -commits, you can still search the file for that query. In this case, update the -document to ensure it links to the most recent version of the file. - -## Navigation - -When documenting navigation through the user interface: - -- Use the exact wording as shown in the UI, including any capital letters as-is. -- Use bold text for navigation items and the char "greater than" (`>`) as a - separator. For example: `Navigate to your project's **Settings > CI/CD**`. -- If there are any expandable menus, make sure to mention that the user needs to - expand the tab to find the settings you're referring to. For example: - `Navigate to your project's **Settings > CI/CD** and expand **General pipelines**`. - -### Navigational elements - -Use the following terms when referring to the main GitLab user interface -elements: - -- **Top menu**: This is the top menu that spans the width of the user interface. - It includes the GitLab logo, search field, counters, and the user's avatar. -- **Left sidebar**: This is the navigation sidebar on the left of the user - interface, specific to the project or group. -- **Right sidebar**: This is the navigation sidebar on the right of the user - interface, specific to the open issue, merge request, or epic. - -## Images - -Images, including screenshots, can help a reader better understand a concept. -However, they can be hard to maintain, and should be used sparingly. - -Before including an image in the documentation, ensure it provides value to the -reader. - -### Capture the image - -Use images to help the reader understand where they are in a process, or how -they need to interact with the application. - -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. -- *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 - a documentation page. For example, if other screenshots include the left - sidebar, include the sidebar in all screenshots. - -### Save the image - -- Save the image with a lowercase file name that is descriptive of the feature - or concept in the image. If the image is of the GitLab interface, append the - GitLab version to the file name, based on the following 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. - -### Add the image link to content - -The Markdown code for including an image in a document is: -`![Image description which will be the alt tag](img/document_image_title_vX_Y.png)` - -The image description is the alt text for the rendered image on the -documentation site. For accessibility and SEO, use [descriptions](https://webaim.org/techniques/alttext/) -that: - -- Are accurate, succinct, and unique. -- Don't use *image of …* or *graphic of…* to describe the image. - -### Remove image shadow - -All images displayed on the [GitLab documentation site](https://docs.gitlab.com) -have a box shadow by default. To remove the box shadow, use the image class -`.image-noshadow` applied directly to an HTML `img` tag: - -```html -<img src="path/to/image.jpg" alt="Alt text (required)" class="image-noshadow"> -``` - -### Compress images - -You should always compress any new images you add to the documentation. One -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. - -GitLab has a [Rake task](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/tasks/pngquant.rake) -that you can use to automate the 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 - been compressed: - - ```shell - bundle exec rake pngquant:lint - ``` - -- Compress all documentation PNG images using `pngquant`: - - ```shell - bundle exec rake pngquant:compress - ``` - -The only caveat is that the task runs on all images under `doc/`, not only the -ones you might have included in a merge request. In that case, you can run the -compress task and only commit the images that are relevant to your merge -request. - -## Videos - -Adding GitLab's existing YouTube video tutorials to the documentation is highly -encouraged, unless the video is outdated. Videos should not replace -documentation, but complement or illustrate it. If content in a video is -fundamental to a feature and its key use cases, but this is not adequately -covered in the documentation, add this detail to the documentation text or -create an issue to review the video and do so. - -Do not upload videos to the product repositories. [Link](#link-to-video) or -[embed](#embed-videos) them instead. - -### Link to video - -To link out to a video, include a YouTube icon so that readers can scan the page -for videos before reading: - -```markdown -<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For an overview, see [Video Title](link-to-video). -``` - -You can link any up-to-date video that is useful to the GitLab user. - -### Embed videos - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/472) in GitLab 12.1. - -The [GitLab documentation site](https://docs.gitlab.com) supports embedded -videos. - -You can only embed videos from [GitLab's official YouTube account](https://www.youtube.com/channel/UCnMGQ8QHMAnVIsI3xJrihhg). -For videos from other sources, [link](#link-to-video) them instead. - -In most cases, it is better to [link to video](#link-to-video) instead, because -an embed takes up a lot of space on the page and can be distracting to readers. - -To embed a video, follow the instructions below and make sure you have your MR -reviewed and approved by a technical writer. - -1. Copy the code below 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). -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">`. -1. In YouTube, select **Share**, and then select **Embed**. -1. Copy the `<iframe>` source (`src`) **URL only** - (`https://www.youtube.com/embed/VIDEO-ID`), - and paste it, replacing the content of the `src` field in the - `iframe` tag. - -```html -leave a blank line here -<div class="video-fallback"> - See the video: <a href="https://www.youtube.com/watch?v=MqL6BMOySIQ">Video title</a>. -</div> -<figure class="video-container"> - <iframe src="https://www.youtube.com/embed/MqL6BMOySIQ" frameborder="0" allowfullscreen="true"> </iframe> -</figure> -leave a blank line here -``` - -This is how it renders on the GitLab documentation site: - -<div class="video-fallback"> - See the video: <a href="https://www.youtube.com/watch?v=enMumwvLAug">What is GitLab</a>. -</div> -<figure class="video-container"> - <iframe src="https://www.youtube.com/embed/MqL6BMOySIQ" frameborder="0" allowfullscreen="true"> </iframe> -</figure> - -> Notes: -> -> - The `figure` tag is required for semantic SEO and the `video_container` -class is necessary to make sure the video is responsive and displays on -different mobile devices. -> - The `<div class="video-fallback">` is a fallback necessary for GitLab's -`/help`, as GitLab's Markdown processor does not support iframes. It's hidden on -the documentation site, but will be displayed on GitLab's `/help`. - -## Code blocks - -- Always wrap code added to a sentence in inline code blocks (`` ` ``). - For example, `.gitlab-ci.yml`, `git add .`, `CODEOWNERS`, or `only: [master]`. - File names, commands, entries, and anything that refers to code should be - added to code blocks. To make things easier for the user, always add a full - code block for things that can be useful to copy and paste, as they can easily - do it with the button on code blocks. -- HTTP methods (`HTTP POST`) and HTTP status codes, both full (`404 File Not Found`) - and abbreviated (`404`), should be wrapped in inline code blocks when used in sentences. - For example: Send a `DELETE` request to delete the runner. Send a `POST` request to create one. -- Add a blank line above and below code blocks. -- When providing a shell command and its output, prefix the shell command with `$` - and leave a blank line between the command and the output. -- When providing a command without output, don't prefix the shell command with `$`. -- If you need to include triple backticks inside a code block, use four backticks - for the codeblock fences instead of three. -- For regular fenced code blocks, always use a highlighting class corresponding to - the language for better readability. Examples: - - ````markdown - ```ruby - Ruby code - ``` - - ```javascript - JavaScript code - ``` - - ```markdown - [Markdown code example](example.md) - ``` - - ```plaintext - Code or text for which no specific highlighting class is available. - ``` - ```` - -Syntax highlighting is required for fenced code blocks added to the GitLab -documentation. Refer to the following table for the most common language classes, -or check the [complete list](https://github.com/rouge-ruby/rouge/wiki/List-of-supported-languages-and-lexers) -of available language classes: - -| Preferred language tags | Language aliases and notes | -|-------------------------|------------------------------------------------------------------------------| -| `asciidoc` | | -| `dockerfile` | Alias: `docker`. | -| `elixir` | | -| `erb` | | -| `golang` | Alias: `go`. | -| `graphql` | | -| `haml` | | -| `html` | | -| `ini` | For some simple config files that are not in TOML format. | -| `javascript` | Alias `js`. | -| `json` | | -| `markdown` | Alias: `md`. | -| `mermaid` | | -| `nginx` | | -| `perl` | | -| `php` | | -| `plaintext` | Examples with no defined language, such as output from shell commands or API calls. If a codeblock has no language, it defaults to `plaintext`. Alias: `text`. | -| `prometheus` | Prometheus configuration examples. | -| `python` | | -| `ruby` | Alias: `rb`. | -| `shell` | Aliases: `bash` or `sh`. | -| `sql` | | -| `toml` | Runner configuration examples, and other TOML-formatted configuration files. | -| `typescript` | Alias: `ts`. | -| `xml` | | -| `yaml` | Alias: `yml`. | - -For a complete reference on code blocks, see the [Kramdown guide](https://about.gitlab.com/handbook/markdown-guide/#code-blocks). - -## GitLab SVG icons - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-docs/-/issues/384) in GitLab 12.7. - -You can use icons from the [GitLab SVG library](https://gitlab-org.gitlab.io/gitlab-svgs/) -directly in the documentation. - -This way, you can achieve a consistent look when writing about interacting with -GitLab user interface elements. - -Usage examples: - -- Icon with default size (16px): `**{icon-name}**` - - Example: `**{tanuki}**` renders as: **{tanuki}**. -- Icon with custom size: `**{icon-name, size}**` - - Available sizes (in px): 8, 10, 12, 14, 16, 18, 24, 32, 48, and 72 - - Example: `**{tanuki, 24}**` renders as: **{tanuki, 24}**. -- Icon with custom size and class: `**{icon-name, size, class-name}**`. - - You can access any class available to this element in GitLab documentation CSS. - - Example with `float-right`, a - [Bootstrap utility class](https://getbootstrap.com/docs/4.4/utilities/float/): - `**{tanuki, 32, float-right}**` renders as: **{tanuki, 32, float-right}** - -### When to use icons - -Icons should be used sparingly, and only in ways that aid and do not hinder the -readability of the text. - -For example, the following adds little to the accompanying text: - -```markdown -1. Go to **{home}** **Project overview > Details** -``` - -1. Go to **{home}** **Project overview > Details** - -However, the following might help the reader connect the text to the user -interface: - -```markdown -| Section | Description | -|:-------------------------|:----------------------------------------------------------------------------------------------------------------------------| -| **{overview}** Overview | View your GitLab Dashboard, and administer projects, users, groups, jobs, runners, and Gitaly servers. | -| **{monitor}** Monitoring | View GitLab system information, and information on background jobs, logs, health checks, requests profiles, and audit logs. | -| **{messages}** Messages | Send and manage broadcast messages for your users. | -``` - -| Section | Description | -|:-------------------------|:----------------------------------------------------------------------------------------------------------------------------| -| **{overview}** Overview | View your GitLab Dashboard, and administer projects, users, groups, jobs, runners, and Gitaly servers. | -| **{monitor}** Monitoring | View GitLab system information, and information on background jobs, logs, health checks, requests profiles, and audit logs. | -| **{messages}** Messages | Send and manage broadcast messages for your users. | - -Use an icon when you find yourself having to describe an interface element. For -example: - -- Do: Select the Admin Area icon ( **{admin}** ). -- Don't: Select the Admin Area icon (the wrench icon). - -## Alert boxes - -When you need to call special attention to particular sentences, use the -following markup to create highlighted alert boxes. - -Alert boxes work for one paragraph only. Multiple paragraphs, lists, and headers -won't render correctly. For multiple lines, use [blockquotes](#blockquotes) -instead. - -Alert boxes render only on the GitLab documentation site (<https://docs.gitlab.com>). -Within GitLab itself, they will appear as plain Markdown text (like the examples -above the rendered versions, below). - -These alert boxes are used in the GitLab documentation. These aren't strict -guidelines, but for consistency you should try to use these values: - -| Color | Markup | Default keyword | Alternative keywords | -|--------|------------|-----------------|----------------------------------------------------------------------| -| Blue | `NOTE:` | `**Note:**` | | -| Yellow | `CAUTION:` | `**Caution:**` | `**Warning:**`, `**Important:**` | -| Red | `DANGER:` | `**Danger:**` | `**Warning:**`, `**Important:**`, `**Deprecated:**`, `**Required:**` | -| Green | `TIP:` | `**Tip:**` | | - -### Note - -Notes indicate additional information that is of special use to the reader. -Notes are most effective when used _sparingly_. - -Try to avoid them. Too many notes can impact the scannability of a topic and -create an overly busy page. - -Instead of adding a note, try one of these alternatives: - -- Re-write the sentence as part of the most-relevant paragraph. -- Put the information into its own standalone paragraph. -- Put the content under a new subheading that introduces the topic, which makes - it more visible. - -If you must use a note, use the following formatting: - -```markdown -NOTE: **Note:** -This is something to note. -``` - -How it renders on the GitLab documentation site: - -NOTE: **Note:** -This is something to note. - -### Tip - -```markdown -TIP: **Tip:** -This is a tip. -``` - -How it renders on the GitLab documentation site: - -TIP: **Tip:** -This is a tip. - -### Caution - -```markdown -CAUTION: **Caution:** -This is something to be cautious about. -``` - -How it renders on the GitLab documentation site: - -CAUTION: **Caution:** -This is something to be cautious about. - -### Danger - -```markdown -DANGER: **Danger:** -This is a breaking change, a bug, or something very important to note. -``` - -How it renders on the GitLab documentation site: - -DANGER: **Danger:** -This is a breaking change, a bug, or something very important to note. - -## Blockquotes - -For highlighting a text within a blue blockquote, use this format: - -```markdown -> This is a blockquote. -``` - -which renders on the [GitLab documentation site](https://docs.gitlab.com) as: - -> This is a blockquote. - -If the text spans across multiple lines it's OK to split the line. - -For multiple paragraphs, use the symbol `>` before every line: - -```markdown -> This is the first paragraph. -> -> This is the second paragraph. -> -> - This is a list item -> - Second item in the list -``` - -Which renders to: - -> This is the first paragraph. -> -> This is the second paragraph. -> -> - This is a list item -> - Second item in the list - -## Terms - -To maintain consistency through GitLab documentation, the following guides -documentation authors on agreed styles and usage of terms. - -### Merge requests (MRs) - -Merge requests allow you to exchange changes you made to source code and -collaborate with other people on the same project. You'll see this term used in -the following ways: - -- Use lowercase *merge requests* regardless of whether referring to the feature - or individual merge requests. - -As noted in the GitLab [Writing Style Guidelines](https://about.gitlab.com/handbook/communication/#writing-style-guidelines), -if you use the **MR** acronym, expand it at least once per document page. -Typically, the first use would be phrased as _merge request (MR)_ with subsequent -instances being _MR_. - -Examples: - -- "We prefer GitLab merge requests". -- "Open a merge request to fix a broken link". -- "After you open a merge request (MR), submit your MR for review and approval". - -### Describe UI elements - -The following are styles to follow when describing user interface elements in an -application: - -- For elements with a visible label, use that label in bold with matching case. - For example, `the **Cancel** button`. -- For elements with a tooltip or hover label, use that label in bold with - matching case. For example, `the **Add status emoji** button`. - -### Verbs for UI elements - -The following are recommended 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" | - -### Other Verbs - -| Recommended | Used for | Replaces | -|:------------|:--------------------------------|:----------------------| -| *go to* | making a browser go to location | "navigate to", "open" | - -## GitLab versions and tiers - -Tagged and released versions of GitLab documentation are available: - -- In the [documentation archives](https://docs.gitlab.com/archives/). -- At the `/help` URL for any GitLab installation. - -The version introducing a new feature is added to the top of the topic in the -documentation to provide a link back to how the feature was developed. - -TIP: **Tip:** -Whenever you have documentation related to the `gitlab.rb` file, you're working -with a self-managed installation. The section or page is therefore likely to -apply only to self-managed instances. If so, the relevant "`TIER` ONLY" -[Product badge](#product-badges) should be included at the highest applicable -heading level. - -### Text for documentation requiring version text - -When a feature is new or updated, you can add version information as a bulleted -item in the **Version history**, or as an inline reference with related text. - -#### Version text in the **Version History** - -If all content in a section is related, add version text in a bulleted list -following the heading for the section. To render correctly, it must be on its -own line and surrounded by blank lines. - -- For features that need to declare the GitLab version that the feature was - introduced. Text similar to the following should be added immediately below - the heading as a blockquote: - - `> Introduced in GitLab 11.3.`. - -- Whenever possible, version text should have a link to the _completed_ issue, - merge request, or epic that introduced the feature. An issue is preferred over - a merge request, and a merge request is preferred over an epic. For example: - - `> [Introduced](<link-to-issue>) in GitLab 11.3.`. - -- If the feature is only available in GitLab Enterprise Edition, mention - the [paid tier](https://about.gitlab.com/handbook/marketing/product-marketing/#tiers) - the feature is available in: - - `> [Introduced](<link-to-issue>) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.3.`. - -- If listing information for multiple version as a feature evolves, add the - information to a block-quoted bullet list. For example: - - ```markdown - > - [Introduced](<link-to-issue>) in GitLab 11.3. - > - Enabled by default in GitLab 11.4. - ``` - -- If a feature is moved to another tier: - - ```markdown - > - [Introduced](<link-to-issue>) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.5. - > - [Moved](<link-to-issue>) to [GitLab Starter](https://about.gitlab.com/pricing/) in 11.8. - > - [Moved](<link-to-issue>) to GitLab Core in 12.0. - ``` - -- If a feature is deprecated, include a link to a replacement (when available): - - ```markdown - > - [Deprecated](<link-to-issue>) in GitLab 11.3. Replaced by [meaningful text](<link-to-appropriate-documentation>). - ``` - - It's also acceptable to describe the replacement in surrounding text, if - available. - - If the deprecation is not obvious in existing text, you may want to include a - warning such as: - - ```markdown - DANGER: **Deprecated:** - This feature was [deprecated](link-to-issue) in GitLab 12.3 - and replaced by [Feature name](link-to-feature-documentation). - ``` - -#### Inline version text - -If you're adding content to an existing topic, you can add version information -inline with the existing text. - -In this case, add `([introduced/deprecated](<link-to-issue>) in GitLab X.X)`. -If applicable, include the paid tier: `([introduced/deprecated](<link-to-issue>) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.4)` - -Including the issue link is encouraged, but isn't a requirement. For example: - -```markdown -The voting strategy (introduced in GitLab 13.4) requires -the primary and secondary voters to agree. -``` - -### Versions in the past or future - -When describing functionality available in past or future versions, use: - -- *Earlier*, and not *older* or *before*. -- *Later*, and not *newer* or *after*. - -For example: - -- Available in GitLab 12.3 and earlier. -- Available in GitLab 12.4 and later. -- If using GitLab 11.4 or earlier, ... -- If using GitLab 10.6 or later, ... - -### Importance of referencing GitLab versions and tiers - -Mentioning GitLab versions and tiers is important to all users and contributors -to quickly have access to the issue or merge request that introduced the change -for reference. Also, they can easily understand what features they have in their -GitLab instance and version, given that the note has some key information. - -`[Introduced](link-to-issue) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.7` -links to the issue that introduced the feature, says which GitLab tier it -belongs to, says the GitLab version that it became available in, and links to -the pricing page in case the user wants to upgrade to a paid tier to use that -feature. - -For example, if you're a regular user and you're looking at the documentation -for a feature you haven't used before, you can immediately see if that feature -is available to you or not. Alternatively, if you've been using a certain -feature for a long time and it changed in some way, it's important to be able to -determine when it changed and what's new in that feature. - -This is even more important as we don't have a perfect process for shipping -documentation. Unfortunately, we still see features without documentation, and -documentation without features. So, for now, we cannot rely 100% on the -documentation site versions. - -Over time, version text will reference a progressively older version of GitLab. -In cases where version text refers to versions of GitLab four or more major -versions back, you can consider removing the text if it's irrelevant or confusing. - -For example, if the current major version is 12.x, version text referencing -versions of GitLab 8.x and older are candidates for removal if necessary for -clearer or cleaner documentation. - -## Products and features - -Refer to the information in this section when describing products and features -within the GitLab product documentation. - -### Avoid line breaks in names - -When entering a product or feature name that includes a space (such as -GitLab Community Edition) or even other companies' products (such as -Amazon Web Services), be sure to not split the product or feature name across -lines with an inserted line break. Splitting product or feature names across -lines makes searching for these items more difficult, and can cause problems if -names change. - -For example, the following Markdown content is *not* formatted correctly: - -```markdown -When entering a product or feature name that includes a space (such as GitLab -Community Edition), don't split the product or feature name across lines. -``` - -Instead, it should appear similar to the following: - -```markdown -When entering a product or feature name that includes a space (such as -GitLab Community Edition), don't split the product or feature name across lines. -``` - -### Product badges - -When a feature is available in paid tiers, add the corresponding tier to the -header or other page element according to the feature's availability: - -| Tier in which feature is available | Tier markup | -|:-----------------------------------------------------------------------|:----------------------| -| GitLab Core and GitLab.com Free, and their higher tiers | `**(CORE)**` | -| GitLab Starter and GitLab.com Bronze, and their higher tiers | `**(STARTER)**` | -| GitLab Premium and GitLab.com Silver, and their higher tiers | `**(PREMIUM)**` | -| GitLab Ultimate and GitLab.com Gold | `**(ULTIMATE)**` | -| *Only* GitLab Core and higher tiers (no GitLab.com-based tiers) | `**(CORE ONLY)**` | -| *Only* GitLab Starter and higher tiers (no GitLab.com-based tiers) | `**(STARTER ONLY)**` | -| *Only* GitLab Premium and higher tiers (no GitLab.com-based tiers) | `**(PREMIUM ONLY)**` | -| *Only* GitLab Ultimate (no GitLab.com-based tiers) | `**(ULTIMATE ONLY)**` | -| *Only* GitLab.com Free and higher tiers (no self-managed instances) | `**(FREE ONLY)**` | -| *Only* GitLab.com Bronze and higher tiers (no self-managed instances) | `**(BRONZE ONLY)**` | -| *Only* GitLab.com Silver and higher tiers (no self-managed instances) | `**(SILVER ONLY)**` | -| *Only* GitLab.com Gold (no self-managed instances) | `**(GOLD ONLY)**` | - -For clarity, all page title headers (H1s) must be have a tier markup for the -lowest tier that has information on the documentation page. - -If sections of a page apply to higher tier levels, they can be separately -labeled with their own tier markup. - -#### Product badge display behavior - -When using the tier markup with headers, the documentation page will display the -full tier badge with the header line. - -You can also use the tier markup with paragraphs, list items, and table cells. -For these cases, the tier mention will be represented by an orange info icon -**{information}** that will display the tiers when visitors point to the icon. -For example: - -- `**(STARTER)**` displays as **(STARTER)** -- `**(STARTER ONLY)**` displays as **(STARTER ONLY)** -- `**(SILVER ONLY)**` displays as **(SILVER ONLY)** - -#### How it works - -Introduced by [!244](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/244), -the special markup `**(STARTER)**` will generate a `span` element to trigger the -badges and tooltips (`<span class="badge-trigger starter">`). When the keyword -*only* is added, the corresponding GitLab.com badge will not be displayed. - -## Specific sections - -Certain styles should be applied to specific sections. Styles for specific -sections are outlined below. - -### GitLab restart - -There are many cases that a restart/reconfigure of GitLab is required. To avoid -duplication, link to the special document that can be found in -[`doc/administration/restart_gitlab.md`](../../administration/restart_gitlab.md). -Usually the text will read like: - -```markdown -Save the file and [reconfigure GitLab](../../administration/restart_gitlab.md) -for the changes to take effect. -``` - -If the document you are editing resides in a place other than the GitLab CE/EE -`doc/` directory, instead of the relative link, use the full path: -`https://docs.gitlab.com/ee/administration/restart_gitlab.html`. Replace -`reconfigure` with `restart` where appropriate. - -### Installation guide - -**Ruby:** -In [step 2 of the installation guide](../../install/installation.md#2-ruby), -we install Ruby from source. Whenever there is a new version that needs to -be updated, remember to change it throughout the codeblock and also replace -the sha256sum (it can be found in the [downloads page](https://www.ruby-lang.org/en/downloads/) -of the Ruby website). - -### Configuration documentation for source and Omnibus installations - -GitLab currently officially supports two installation methods: installations -from source and Omnibus packages installations. - -Whenever there is a setting that is configurable for both installation methods, -prefer to document it in the CE documentation to avoid duplication. - -Configuration settings include: - -1. Settings that touch configuration files in `config/`. -1. NGINX settings and settings in `lib/support/` in general. - -When there is a list of steps to perform, usually that entails editing the -configuration file and reconfiguring/restarting GitLab. In such case, follow -the style below as a guide: - -````markdown -**For Omnibus installations** - -1. Edit `/etc/gitlab/gitlab.rb`: - - ```ruby - external_url "https://gitlab.example.com" - ``` - -1. Save the file and [reconfigure](path/to/administration/restart_gitlab.md#omnibus-gitlab-reconfigure) - GitLab for the changes to take effect. - ---- - -**For installations from source** - -1. Edit `config/gitlab.yml`: - - ```yaml - gitlab: - host: "gitlab.example.com" - ``` - -1. Save the file and [restart](path/to/administration/restart_gitlab.md#installations-from-source) - GitLab for the changes to take effect. -```` - -In this case: - -- Before each step list the installation method is declared in bold. -- Three dashes (`---`) are used to create a horizontal line and separate the two - methods. -- The code blocks are indented one or more spaces under the list item to render - correctly. -- Different highlighting languages are used for each config in the code block. -- The [GitLab Restart](#gitlab-restart) section is used to explain a required - restart or reconfigure of GitLab. - -### Troubleshooting - -For troubleshooting sections, you should provide as much context as possible so -users can identify the problem they are facing and resolve it on their own. You -can facilitate this by making sure the troubleshooting content addresses: - -1. The problem the user needs to solve. -1. How the user can confirm they have the problem. -1. Steps the user can take towards resolution of the problem. - -If the contents of each category can be summarized in one line and a list of -steps aren't required, consider setting up a [table](#tables) with headers of -*Problem* \| *Cause* \| *Solution* (or *Workaround* if the fix is temporary), or -*Error message* \| *Solution*. - -## Feature flags - -Learn how to [document features deployed behind flags](feature_flags.md). For -guidance on developing GitLab with feature flags, see [Feature flags in development of GitLab](../feature_flags/index.md). - -## GraphQL API - -GraphQL APIs are different from [RESTful APIs](restful_api_styleguide.md). Reference -information is generated in our [GraphQL reference](../../api/graphql/reference/index.md). - -However, it's helpful to include examples on how to use GraphQL for different -*use cases*, with samples that readers can use directly in the -[GraphiQL explorer](../api_graphql_styleguide.md#graphiql). - -This section describes the steps required to add your GraphQL examples to -GitLab documentation. - -### Add a dedicated GraphQL page - -To create a dedicated GraphQL page, create a new `.md` file in the -`doc/api/graphql/` directory. Give that file a functional name, such as -`import_from_specific_location.md`. - -### Start the page with an explanation - -Include a page title that describes the GraphQL functionality in a few words, -such as: - -```markdown -# Search for [substitute kind of data] -``` - -Describe the search. One sentence may be all you need. More information may -help readers learn how to use the example for their GitLab deployments. - -### Include a procedure using the GraphiQL explorer - -The GraphiQL explorer can help readers test queries with working deployments. -Set up the section with the following: - -- Use the following title: - - ```markdown - ## Set up the GraphiQL explorer - ``` - -- Include a code block with the query that anyone can include in their - instance of the GraphiQL explorer: - - ````markdown - ```graphql - query { - <insert queries here> - } - ``` - ```` - -- Tell the user what to do: - - ```markdown - 1. Open the GraphiQL explorer tool in the following URL: `https://gitlab.com/-/graphql-explorer`. - 1. Paste the `query` listed above into the left window of your GraphiQL explorer tool. - 1. Select Play to get the result shown here: - ``` - -- Include a screenshot of the result in the GraphiQL explorer. Follow the naming - convention described in the [Save the image](#save-the-image) section. -- Follow up with an example of what you can do with the output. Make sure the - example is something that readers can do on their own deployments. -- Include a link to the [GraphQL API resources](../../api/graphql/reference/index.md). - -### Add the GraphQL example to the Table of Contents - -You'll need to open a second MR, against the [GitLab documentation repository](https://gitlab.com/gitlab-org/gitlab-docs/). - -We store our Table of Contents in the `default-nav.yaml` file, in the -`content/_data` subdirectory. You can find the GraphQL section under the -following line: - -```yaml -- category_title: GraphQL -``` - -Be aware that CI tests for that second MR will fail with a bad link until the -main MR that adds the new GraphQL page is merged. - -And that's all you need! +This document was moved to [another location](styleguide/index.md). diff --git a/doc/development/documentation/styleguide/index.md b/doc/development/documentation/styleguide/index.md new file mode 100644 index 00000000000..41e38266a58 --- /dev/null +++ b/doc/development/documentation/styleguide/index.md @@ -0,0 +1,1999 @@ +--- +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/#designated-technical-writers +description: 'Writing styles, markup, formatting, and other standards for GitLab Documentation.' +--- + +# Documentation Style Guide + +This document defines the standards for GitLab's documentation content and +files. + +For broader information about the documentation, see the [Documentation guidelines](index.md). + +For guidelines specific to text in the GitLab interface, see the Pajamas [Content](https://design.gitlab.com/content/error-messages/) section. + +For information on how to validate styles locally or by using GitLab CI/CD, see [Testing](../testing.md). + +Use this guide for standards on grammar, formatting, word usage, and more. + +You can also view a list of [recent updates to this guide](https://gitlab.com/dashboard/merge_requests?scope=all&utf8=%E2%9C%93&state=merged&label_name[]=tw-style¬[label_name][]=docs%3A%3Afix). + +If you can't find what you need: + +- View the GitLab Handbook for [writing style guidelines](https://about.gitlab.com/handbook/communication/#writing-style-guidelines) that apply to all GitLab content. +- Refer to one of the following: + + - [Microsoft Style Guide](https://docs.microsoft.com/en-us/style-guide/welcome/). + - [Google Developer Documentation Style Guide](https://developers.google.com/style). + +If you have questions about style, mention `@tw-style` in an issue or merge request, or, if you have access to the GitLab Slack workspace, use `#docs-process`. + +## Documentation is the single source of truth (SSOT) + +### Why a single source of truth + +The documentation of GitLab products and features is the SSOT for all +information related to implementation, usage, and troubleshooting. It evolves +continuously, in keeping with new products and features, and with improvements +for clarity, accuracy, and completeness. + +This policy prevents information silos, making it easier to find information +about GitLab products. + +It also informs decisions about the kinds of content we include in our +documentation. + +### All information + +Include problem-solving actions that may address rare cases or be considered +_risky_, so long as proper context is provided in the form of 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 +Technical Writing team. + +We will add all troubleshooting information to the documentation, no matter how +unlikely a user is to encounter a situation. For the [Troubleshooting sections](#troubleshooting), +people in GitLab Support can merge additions themselves. + +### All media types + +Include any media types/sources if the content is relevant to readers. You can +freely include or link presentations, diagrams, videos, and so on; no matter who +it was originally composed for, if it is helpful to any of our audiences, we can +include it. + +- If you use an image that has a separate source file (for example, a vector or + diagram format), link the image to the source file so that it may be reused or + updated by anyone. +- Do not copy and paste content from other sources unless it is a limited + quotation with the source cited. Typically it is better to either rephrase + relevant information in your own words or link out to the other source. + +### No special types + +In the software industry, it is a best practice to organize documentation in +different types. For example, [Divio recommends](https://www.divio.com/blog/documentation/): + +- Tutorials +- How-to guides +- Explanation +- Reference (for example, a glossary) + +At GitLab, we have so many product changes in our monthly releases that we can't +afford to continuously update multiple types of information. If we have multiple +types, the information will become outdated. Therefore, we have a +[single template](../structure.md) for documentation. + +We currently do not distinguish specific document types, although we are open to +reconsidering this policy after the documentation has reached a future stage of +maturity and quality. If you are reading this, then despite our continuous +improvement efforts, that point hasn't been reached. + +### Link instead of summarize + +There is a temptation to summarize the information on another page. This will +cause the information to live in two places. Instead, link to the single source +of truth and explain why it is important to consume the information. + +### Organize by topic, not by type + +Beyond top-level audience-type folders (for example, `administration`), we +organize content by topic, not by type, so it can be located in the +single-source-of-truth (SSOT) section for the subject matter. + +For example, do not create groupings of similar media types. For example: + +- Glossaries. +- FAQs. +- Sets of all articles or videos. + +Such grouping of content by type makes it difficult to browse for the information +you need and difficult to maintain up-to-date content. Instead, organize content +by its subject (for example, everything related to CI goes together) and +cross-link between any related content. + +### Docs-first methodology + +We employ a _documentation-first methodology_ to help ensure the documentation +remains a complete and trusted resource, and to make communicating about the use +of GitLab more efficient. + +- If the answer to a question exists in documentation, share the link to the + documentation instead of rephrasing the information. +- When you encounter new information not available in GitLab’s documentation (for + example, when working on a support case or testing a feature), your first step + should be to create a merge request (MR) to add this information to the + documentation. You can then share the MR to communicate this information. + +New information that would be useful toward the future usage or troubleshooting +of GitLab should not be written directly in a forum or other messaging system, +but added to a documentation MR and then referenced, as described above. Note +that among any other documentation changes, you can either: + +- Add a [Troubleshooting section](#troubleshooting) to a doc if none exists. +- Un-comment and use the placeholder Troubleshooting section included as part of + our [documentation template](../structure.md#template-for-new-docs), if present. + +The more we reflexively add useful information to the documentation, the more +(and more successfully) the documentation will be used to efficiently accomplish +tasks and solve problems. + +If you have questions when considering, authoring, or editing documentation, ask +the Technical Writing team on Slack in `#docs` or in GitLab by mentioning the +writer for the applicable [DevOps stage](https://about.gitlab.com/handbook/product/product-categories/#devops-stages). +Otherwise, forge ahead with your best effort. It does not need to be perfect; +the team is happy to review and improve upon your content. Review the +[Documentation guidelines](index.md) before you begin your first documentation MR. + +Having a knowledge base in any form that's separate from the documentation would +be against the documentation-first methodology, because the content would overlap with +the documentation. + +## Markdown + +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 +will support all [GFM markup](../../../user/markdown.md) in the future, which is +all markup supported for display in the GitLab application itself. For now, use +regular Markdown markup, following the rules in the linked style guide. + +Note that Kramdown-specific markup (for example, `{:.class}`) doesn't render +properly on GitLab instances under [`/help`](../index.md#gitlab-help). + +### HTML in Markdown + +Hard-coded HTML is valid, although it's discouraged from being used while we +have `/help`. HTML is permitted if: + +- There's no equivalent markup in Markdown. +- Advanced tables are necessary. +- Special styling is required. +- Reviewed and approved by a technical writer. + +### Markdown Rules + +GitLab ensures that the Markdown used across all documentation is consistent, as +well as easy to review and maintain, by [testing documentation changes](../testing.md) +with [markdownlint](../testing.md#markdownlint). This lint test fails when any +document has an issue with Markdown formatting that may cause the page to render +incorrectly within GitLab. It will also fail when a document is using +non-standard Markdown (which may render correctly, but is not the current +standard for GitLab documentation). + +#### Markdown rule `MD044/proper-names` (capitalization) + +A rule that could cause confusion is `MD044/proper-names`, as it might not be +immediately clear what caused markdownlint to fail, or how to correct the +failure. This rule checks a list of known words, listed in the `.markdownlint.json` +file in each project, to verify proper use of capitalization and backticks. +Words in backticks will be ignored by markdownlint. + +In general, product names should follow the exact capitalization of the official +names of the products, protocols, and so on. See [`.markdownlint.json`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.markdownlint.json) +for the words tested for proper capitalization in GitLab documentation. + +Some examples fail if incorrect capitalization is used: + +- MinIO (needs capital `IO`) +- NGINX (needs all capitals) +- runit (needs lowercase `r`) + +Additionally, commands, parameters, values, filenames, and so on must be +included in backticks. For example: + +- "Change the `needs` keyword in your `.gitlab.yml`..." + - `needs` is a parameter, and `.gitlab.yml` is a file, so both need backticks. + Additionally, `.gitlab.yml` will fail markdownlint without backticks as it + does not have capital G or L. +- "Run `git clone` to clone a Git repository..." + - `git clone` is a command, so it must be lowercase, while Git is the product, + so it must have a capital G. + +## Structure + +Because we want documentation to be a SSOT, we should [organize by topic, not by +type](#organize-by-topic-not-by-type). + +### Folder structure overview + +The documentation is separated by top-level audience folders [`user`](https://gitlab.com/gitlab-org/gitlab-foss/tree/master/doc/user), +[`administration`](https://gitlab.com/gitlab-org/gitlab-foss/tree/master/doc/administration), +and [`development`](https://gitlab.com/gitlab-org/gitlab-foss/tree/master/doc/development) +(contributing) folders. + +Beyond that, we primarily follow the structure of the GitLab user interface or +API. + +Our goal is to have a clear hierarchical structure with meaningful URLs like +`docs.gitlab.com/user/project/merge_requests/`. With this pattern, you can +immediately tell that you are navigating to user-related documentation about +Project features; specifically about Merge Requests. Our site's paths match +those of our repository, so the clear structure also makes documentation easier +to update. + +Put files for a specific product area into the related folder: + +| Directory | What belongs here | +|:----------------------|:----------------------------------------------------------------------------------------------------------------------------------------| +| `doc/user/` | User related documentation. Anything that can be done within the GitLab user interface goes here, including usage of the `/admin` interface. | +| `doc/administration/` | Documentation that requires the user to have access to the server where GitLab is installed. The admin settings that can be accessed by using GitLab's interface exist under `doc/user/admin_area/`. | +| `doc/api/` | API related documentation. | +| `doc/development/` | Documentation related to the development of GitLab, whether contributing code or documentation. Related process and style guides should go here. | +| `doc/legal/` | Legal documents about contributing to GitLab. | +| `doc/install/` | Contains instructions for installing GitLab. | +| `doc/update/` | Contains instructions for updating GitLab. | +| `doc/topics/` | Indexes per topic (`doc/topics/topic_name/index.md`): all resources for that topic. | + +### Work with directories and files + +Refer to the following items when working with directories and files: + +1. When you create a new directory, always start with an `index.md` file. + Don't use another file name 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, + proper naming would be `import_project/import_from_github.md`. This applies + to both image files and Markdown files. +1. For image files, do not exceed 100KB. +1. Do not upload video files to the product repositories. + [Link or embed videos](#videos) instead. +1. There are four main directories: `user`, `administration`, `api`, and + `development`. +1. The `doc/user/` directory has five main subdirectories: `project/`, `group/`, + `profile/`, `dashboard/` and `admin_area/`. + - `doc/user/project/` should contain all project related documentation. + - `doc/user/group/` should contain all group related documentation. + - `doc/user/profile/` should contain all profile related documentation. + Every page you would navigate under `/profile` should have its own document, + for example, `account.md`, `applications.md`, or `emails.md`. + - `doc/user/dashboard/` should contain all dashboard related documentation. + - `doc/user/admin_area/` should contain all admin related documentation + describing what can be achieved by accessing GitLab's admin interface + (_not to be confused with `doc/administration` where server access is + required_). + - Every category under `/admin/application_settings/` should have its + own document located at `doc/user/admin_area/settings/`. For example, + the **Visibility and Access Controls** category should have a document + located at `doc/user/admin_area/settings/visibility_and_access_controls.md`. +1. The `doc/topics/` directory holds topic-related technical content. Create + `doc/topics/topic_name/subtopic_name/index.md` when subtopics become necessary. + General user- and admin- related documentation, should be placed accordingly. +1. The `/university/` directory is *deprecated* and the majority of its documentation + has been moved. + +If you're unsure where to place a document or a content addition, this shouldn't +stop you from authoring and contributing. Use your best judgment, and then ask +the reviewer of your MR to confirm your decision, or ask a technical writer at +any stage in the process. The technical writing team will review all +documentation changes, regardless, and can move content if there is a better +place for it. + +### Avoid duplication + +Do not include the same information in multiple places. +[Link to a single source of truth instead.](#link-instead-of-summarize) + +### References across documents + +- Give each folder an `index.md` page that introduces the topic, introduces the + pages within, and links to the pages within (including to the index pages of + any next-level subpaths). +- To ensure discoverability, ensure each new or renamed doc is linked from its + higher-level index page and other related pages. +- When making reference to other GitLab products and features, link to their + respective documentation, at least on first mention. +- When making reference to third-party products or technologies, link out to + their external sites, documentation, and resources. + +### Structure within documents + +- Include any and all applicable subsections as described on the + [structure and template](../structure.md) page. +- Structure content in alphabetical order in tables, lists, and so on, unless + there's a logical reason not to (for example, when mirroring the user + interface or an otherwise ordered sequence). + +## Language + +GitLab documentation should be clear and easy to understand. + +- Be clear, concise, and stick to the goal of the documentation. +- Write in US English with US grammar. (Tested in [`British.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/British.yml).) +- Use [inclusive language](#inclusive-language). + +### Point of view + +In most cases, it’s appropriate to use the second-person (you, yours) point of +view, because it’s friendly and easy to understand. (Tested in +[`FirstPerson.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/FirstPerson.yml).) + +### Capitalization + +#### Headings + +Use sentence case. For example: + +- `# Use variables to configure pipelines` +- `## Use the To-Do List` + +#### UI text + +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. + +If you think there's a mistake in the way the user interface text is styled, +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)) +- *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. + +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) +by default. + +#### Other terms + +Capitalize names of: + +- GitLab [product tiers](https://about.gitlab.com/pricing/). For example, + GitLab Core and GitLab Ultimate. (Tested in [`BadgeCapitalization.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/BadgeCapitalization.yml).) +- Third-party organizations, software, and products. For example, Prometheus, + Kubernetes, Git, and The Linux Foundation. +- Methods or methodologies. For example, Continuous Integration, + Continuous Deployment, Scrum, and Agile. (Tested in [`.markdownlint.json`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.markdownlint.json).) + +Follow the capitalization style listed at the [authoritative source](#links-to-external-documentation) +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**. + +### Inclusive language + +We strive to create documentation that's inclusive. This section includes +guidance and examples for the following categories: + +- [Gender-specific wording](#avoid-gender-specific-wording). + (Tested in [`InclusionGender.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionGender.yml).) +- [Ableist language](#avoid-ableist-language). + (Tested in [`InclusionAbleism.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionAbleism.yml).) +- [Cultural sensitivity](#culturally-sensitive-language). + (Tested in [`InclusionCultural.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionCultural.yml).) + +We write our developer documentation with inclusivity and diversity in mind. This +page is not an exhaustive reference, but describes some general guidelines and +examples that illustrate some best practices to follow. + +#### Avoid gender-specific wording + +When possible, use gender-neutral pronouns. For example, you can use a singular +[they](https://developers.google.com/style/pronouns#gender-neutral-pronouns) as +a gender-neutral pronoun. + +Avoid the use of gender-specific pronouns, unless referring to a specific person. + +<!-- vale gitlab.InclusionGender = NO --> + +| Use | Avoid | +|-----------------------------------|---------------------------------| +| People, humanity | Mankind | +| GitLab Team Members | Manpower | +| You can install; They can install | He can install; She can install | + +<!-- vale gitlab.InclusionGender = YES --> + +If you need to set up [Fake user information](#fake-user-information), use +diverse or non-gendered names with common surnames. + +#### Avoid ableist language + +Avoid terms that are also used in negative stereotypes for different groups. + +<!-- vale gitlab.InclusionAbleism = NO --> + +| Use | Avoid | +|------------------------|----------------------| +| Check for completeness | Sanity check | +| Uncertain outliers | Crazy outliers | +| Slows the service | Cripples the service | +| Placeholder variable | Dummy variable | +| Active/Inactive | Enabled/Disabled | +| On/Off | Enabled/Disabled | + +<!-- vale gitlab.InclusionAbleism = YES --> + +Credit: [Avoid ableist language](https://developers.google.com/style/inclusive-documentation#ableist-language) +in the Google Developer Style Guide. + +#### Culturally sensitive language + +Avoid terms that reflect negative cultural stereotypes and history. In most +cases, you can replace terms such as `master` and `slave` with terms that are +more precise and functional, such as `primary` and `secondary`. + +<!-- vale gitlab.InclusionCultural = NO --> + +| Use | Avoid | +|----------------------|-----------------------| +| Primary / secondary | Master / slave | +| Allowlist / denylist | Blacklist / whitelist | + +<!-- vale gitlab.InclusionCultural = YES --> + +For more information see the following [Internet Draft specification](https://tools.ietf.org/html/draft-knodel-terminology-02). + +### 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: + +- _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`. + +### Fake URLs + +When including sample URLs in the documentation, use: + +- `example.com` when the domain name is generic. +- `gitlab.example.com` when referring to self-managed instances of GitLab. + +### Fake tokens + +There may be times where a token is needed to demonstrate an API call using +cURL or a variable used in CI. It is strongly advised not to use real tokens in +documentation even if the probability of a token being exploited is low. + +You can use the following fake tokens as examples: + +| Token type | Token value | +|:----------------------|:-------------------------------------------------------------------| +| Private user token | `<your_access_token>` | +| Personal access token | `n671WNGecHugsdEDPsyo` | +| Application ID | `2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6` | +| Application secret | `04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df` | +| CI/CD variable | `Li8j-mLUVA3eZYjPfd_H` | +| Specific runner token | `yrnZW46BrtBFqM7xDzE7dddd` | +| Shared runner token | `6Vk7ZsosqQyfreAxXTZr` | +| Trigger token | `be20d8dcc028677c931e04f3871a9b` | +| Webhook secret token | `6XhDroRcYPM5by_h-HLY` | +| Health check token | `Tu7BgjR9qeZTEyRzGG2P` | +| Request profile token | `7VgpS4Ax5utVD2esNstz` | + +### Language to avoid + +When creating documentation, limit or avoid the use of the following verb +tenses, words, and phrases: + +- Avoid jargon when possible, and when not possible, define the term or + [link to a definition](#links-to-external-documentation). +- Avoid uncommon words when a more-common alternative is possible, ensuring that + content is accessible to more readers. +- Don't write in the first person singular. + (Tested in [`FirstPerson.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/FirstPerson.yml).) + - Instead of _I_ or _me_, use _we_, _you_, _us_, or _one_. + - When possible, stay user focused by writing in the second person (_you_ or + the imperative). +- Don't overuse "that". In many cases, you can remove "that" from a sentence + and improve readability. +- Avoid use of the future tense: + - Instead of "after you execute this command, GitLab will display the + result", use "after you execute this command, GitLab displays the result". + - Only use the future tense to convey when the action or result will actually + occur at a future time. +- Don't use slashes to clump different words together or as a replacement for + the word "or": + - Instead of "and/or," consider using "or," or use another sensible + construction. + - Other examples include "clone/fetch," author/assignee," and + "namespace/repository name." Break apart any such instances in an + appropriate way. + - Exceptions to this rule include commonly accepted technical terms, such as + CI/CD and TCP/IP. +<!-- vale gitlab.LatinTerms = NO --> +- We discourage the use of Latin abbreviations and terms, such as _e.g._, + _i.e._, _etc._, or _via_, as even native users of English can misunderstand + those terms. (Tested in [`LatinTerms.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/LatinTerms.yml).) + - Instead of _i.e._, use _that is_. + - Instead of _via_, use _through_. + - Instead of _e.g._, use _for example_, _such as_, _for instance_, or _like_. + - Instead of _etc._, either use _and so on_ or consider editing it out, since + it can be vague. +<!-- vale gitlab.LatinTerms = YES --> +- Avoid using the word *currently* when talking about the product or its + features. The documentation describes the product as it is, and not as it + will be at some indeterminate point in the future. +- Avoid the using the word *scalability* with increasing GitLab's performance + for additional users. Using the words *scale* or *scaling* in other cases is + acceptable, but references to increasing GitLab's performance for additional + users should direct readers to the GitLab + [reference architectures](../../../administration/reference_architectures/index.md) + page. +- Avoid all forms of the phrases *high availability* and *HA*, and instead + direct readers to the GitLab [reference architectures](../../../administration/reference_architectures/index.md) + for information about configuring GitLab to have the performance needed for + additional users over time. +- Don't use profanity or obscenities. Doing so may negatively affect other + users and contributors, which is contrary to GitLab's value of + [Diversity, Inclusion, and Belonging](https://about.gitlab.com/handbook/values/#diversity-inclusion). +- Avoid the use of [racially-insensitive terminology or phrases](https://www.marketplace.org/2020/06/17/tech-companies-update-language-to-avoid-offensive-terms/). For example: + - Use *primary* and *secondary* for database and server relationships. + - Use *allowlist* and *denylist* to describe access control lists. +- Avoid the word _please_. For details, see the [Microsoft style guide](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/p/please). +- Avoid words like _easily_, _simply_, _handy_, and _useful._ If the user + doesn't find the process to be these things, we lose their trust. + +### Word usage clarifications + +- Don't use "may" and "might" interchangeably: + - Use "might" to indicate the probability of something occurring. "If you + skip this step, the import process might fail." + - Use "may" to indicate giving permission for someone to do something, or + consider using "can" instead. "You may select either option on this + screen." Or, "You can select either option on this screen." + +### Contractions + +Contractions are encouraged, and can create a friendly and informal tone, +especially in tutorials, instructional documentation, and +[user interfaces](https://design.gitlab.com/content/punctuation/#contractions). + +Some contractions, however, should be avoided: + +- Do not use contractions with a proper noun and a verb. For example: + + | Do | Don't | + |------------------------------------------|-----------------------------------------| + | GitLab is creating X. | GitLab's creating X. | + +- Do not use contractions when you need to emphasize a negative. For example: + + | Do | Don't | + |------------------------------------------|-----------------------------------------| + | Do *not* install X with Y. | *Don't* install X with Y. | + +- Do not use contractions in reference documentation. For example: + + | Do | Don't | + |------------------------------------------|-----------------------------------------| + | Do *not* set a limit greater than 1000. | *Don't* set a limit greater than 1000. | + | For `parameter1`, the default is 10. | For `parameter1`, the default's 10. | + +- Avoid contractions in error messages. Examples: + + | Do | Don't | + |------------------------------------------|-----------------------------------------| + | Requests to localhost are not allowed. | Requests to localhost aren't allowed. | + | Specified URL cannot be used. | Specified URL can't be used. | + +## Text + +- [Write in Markdown](#markdown). +- Splitting long lines (preferably up to 100 characters) can make it easier to + provide feedback on small chunks of text. +- Insert an empty line for new paragraphs. +- Insert an empty line between different markups (for example, after every + paragraph, header, list, and so on). Example: + + ```markdown + ## Header + + Paragraph. + + - List item 1 + - List item 2 + ``` + +### Emphasis + +- Use double asterisks (`**`) to mark a word or text in bold (`**bold**`). +- Use underscore (`_`) for text in italics (`_italic_`). +- Use greater than (`>`) for blockquotes. + +### Punctuation + +Follow these guidelines for punctuation: + +<!-- vale gitlab.Repetition = NO --> + +| Rule | Example | +|------------------------------------------------------------------|--------------------------------------------------------| +| 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._ | +| Always use lowercase after a colon. | _Related Issues: a way to create a relationship between issues._ | + +<!-- vale gitlab.Repetition = YES --> + +### Placeholder text + +Often in examples, a writer will provide a command or configuration that +uses values specific to the reader. + +In these cases, use [`<` and `>`](https://en.wikipedia.org/wiki/Usage_message#Pattern) +to call out where a reader must replace text with their own value. + +For example: + +```shell +cp <your_source_directory> <your_destination_directory> +``` + +### Keyboard commands + +Use the HTML `<kbd>` tag when referring to keystroke presses. For example: + +```plaintext +To stop the command, press <kbd>Ctrl</kbd>+<kbd>C</kbd>. +``` + +When the docs are generated, the output is: + +To stop the command, press <kbd>Ctrl</kbd>+<kbd>C</kbd>. + +## Lists + +- Always start list items with a capital letter, unless they're parameters or + commands that are in backticks, or similar. +- Always leave a blank line before and after a list. +- Begin a line with spaces (not tabs) to denote a [nested sub-item](#nesting-inside-a-list-item). + +### Ordered vs. unordered lists + +Only use ordered lists when their items describe a sequence of steps to follow. + +Do: + +```markdown +These are the steps to do something: + +1. First, do the first step. +1. Then, do the next step. +1. Finally, do the last step. +``` + +Don't: + +```markdown +This is a list of available features: + +1. Feature 1 +1. Feature 2 +1. Feature 3 +``` + +### Markup + +- Use dashes (`-`) for unordered lists instead of asterisks (`*`). +- Prefix `1.` to every item in an ordered list. When rendered, the list items + will appear with sequential numbering. + +### Punctuation + +- Don't add commas (`,`) or semicolons (`;`) to the ends of list items. +- Only add periods to the end of a list item if the item consists of a complete + sentence (with a subject and a verb). +- Be consistent throughout the list: if the majority of the items do not end in + a period, do not end any of the items in a period, even if they consist of a + complete sentence. The opposite is also valid: if the majority of the items + end with a period, end all with a period. +- Separate list items from explanatory text with a colon (`:`). For example: + + ```markdown + The list is as follows: + + - First item: this explains the first item. + - Second item: this explains the second item. + ``` + +**Examples:** + +Do: + +- First list item +- Second list item +- Third list item + +Don't: + +- First list item +- Second list item +- Third list item. + +Do: + +- Let's say this is a complete sentence. +- Let's say this is also a complete sentence. +- Not a complete sentence. + +Don't (vary use of periods; majority rules): + +- Let's say this is a complete sentence. +- Let's say this is also a complete sentence. +- Not a complete sentence + +### Nesting inside a list item + +It's possible to nest items under a list item, so that they render with the same +indentation as the list item. This can be done with: + +- [Code blocks](#code-blocks) +- [Blockquotes](#blockquotes) +- [Alert boxes](#alert-boxes) +- [Images](#images) + +Items nested in lists should always align with the first character of the list +item. In unordered lists (using `-`), this means two spaces for each level of +indentation: + +````markdown +- Unordered list item 1 + + A line nested using 2 spaces to align with the `U` above. + +- Unordered list item 2 + + > A quote block that will nest + > inside list item 2. + +- Unordered list item 3 + + ```plaintext + a codeblock that will next inside list item 3 + ``` + +- Unordered list item 4 + + ![an image that will nest inside list item 4](image.png) +```` + +For ordered lists, use three spaces for each level of indentation: + +````markdown +1. Ordered list item 1 + + A line nested using 3 spaces to align with the `O` above. + +1. Ordered list item 2 + + > A quote block that will nest + > inside list item 2. + +1. Ordered list item 3 + + ```plaintext + a codeblock that will next inside list item 3 + ``` + +1. Ordered list item 4 + + ![an image that will nest inside list item 4](image.png) +```` + +You can nest full lists inside other lists using the same rules as above. If you +want to mix types, that's also possible, if you don't mix items at the same +level: + +```markdown +1. Ordered list item one. +1. Ordered list item two. + - Nested unordered list item one. + - Nested unordered list item two. +1. Ordered list item three. + +- Unordered list item one. +- Unordered list item two. + 1. Nested ordered list item one. + 1. Nested ordered list item two. +- Unordered list item three. +``` + +## Tables + +Tables should be used to describe complex information in a straightforward +manner. Note that in many cases, an unordered list is sufficient to describe a +list of items with a single, simple description per item. But, if you have data +that's best described by a matrix, tables are the best choice. + +### Creation guidelines + +Due to accessibility and scannability requirements, tables should not have any +empty cells. If there is no otherwise meaningful value for a cell, consider entering +*N/A* (for 'not applicable') or *none*. + +To help tables be easier to maintain, consider adding additional spaces to the +column widths to make them consistent. For example: + +```markdown +| App name | Description | Requirements | +|:---------|:---------------------|:---------------| +| App 1 | Description text 1. | Requirements 1 | +| App 2 | Description text 2. | None | +``` + +Consider installing a plugin or extension in your editor for formatting tables: + +- [Markdown Table Prettifier](https://marketplace.visualstudio.com/items?itemName=darkriszty.markdown-table-prettify) for Visual Studio Code +- [Markdown Table Formatter](https://packagecontrol.io/packages/Markdown%20Table%20Formatter) for Sublime Text +- [Markdown Table Formatter](https://atom.io/packages/markdown-table-formatter) for Atom + +### Feature tables + +When creating tables of lists of features (such as whether or not features are +available to certain roles on the [Permissions](../../../user/permissions.md#project-members-permissions) +page), use the following phrases (based on the SVG icons): + +| Option | Markdown | Displayed result | +|--------|--------------------------|------------------------| +| No | `**{dotted-circle}** No` | **{dotted-circle}** No | +| Yes | `**{check-circle}** Yes` | **{check-circle}** Yes | + +## Quotes + +Valid for Markdown content only, not for front matter entries: + +- Standard quotes: double quotes (`"`). Example: "This is wrapped in double + quotes". +- Quote within a quote: double quotes (`"`) wrap single quotes (`'`). Example: + "I am 'quoting' something within a quote". + +For other punctuation rules, refer to the +[GitLab UX guide](https://design.gitlab.com/content/punctuation/). + +## Headings + +- Add _only one H1_ in each document, by adding `#` at the beginning of + it (when using Markdown). The `h1` will be 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` +- Avoid putting numbers in headings. Numbers shift, hence documentation anchor + links shift too, which eventually leads to dead links. If you think it is + compelling to add numbers in headings, make sure to at least discuss it with + someone in the Merge Request. +- [Avoid using symbols and special characters](https://gitlab.com/gitlab-org/gitlab-docs/-/issues/84) + in headers. Whenever possible, they should be plain and short text. +- When possible, avoid including words that might change in the future. Changing + a heading changes its anchor URL, which affects other linked pages. +- When introducing a new document, be careful for the headings to be + grammatically and syntactically correct. Mention an [assigned technical writer (TW)](https://about.gitlab.com/handbook/product/product-categories/) + for review. + This is to ensure that no document with wrong heading is going live without an + audit, thus preventing dead links and redirection issues when corrected. +- Leave exactly one blank line before and after a heading. +- Do not use links in headings. +- Add the corresponding [product badge](#product-badges) according to the tier the + feature belongs. +- Our documentation site search engine prioritizes words used in headings and + subheadings. Make you subheading titles clear, descriptive, and complete to help + users find the right example, as shown in the section on [heading titles](#heading-titles). +- See [Capitalization](#capitalization) for guidelines on capitalizing headings. + +### Heading titles + +Keep heading titles clear and direct. Make every word count. To accommodate +search engine optimization (SEO), use the imperative, where possible. + +| Do | Don't | +|:--------------------------------------|:------------------------------------------------------------| +| Configure GDK | Configuring GDK | +| GitLab Release and Maintenance Policy | This section covers GitLab's Release and Maintenance Policy | +| Backport to older releases | Backporting to older releases | +| GitLab Pages examples | Examples | + +For guidelines on capitalizing headings, see the section on [capitalization](#capitalization). + +NOTE: **Note:** +If you change an existing title, be careful. These changes might affect not +only [links](#anchor-links) within the page, but might also affect links to the +GitLab documentation from both the GitLab application and external sites. + +### Anchor links + +Headings generate anchor links when rendered. `## This is an example` generates +the anchor `#this-is-an-example`. + +NOTE: **Note:** +[Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/39717) in +GitLab 13.4, [product badges](#product-badges) used in headings aren't included +in the generated anchor links. For example, when you link to +`## This is an example **(CORE)**`, use the anchor `#this-is-an-example`. + +Keep in mind that the GitLab user interface links to many documentation pages +and anchor links to take the user to the right spot. Therefore, when you change +a heading, search `doc/*`, `app/views/*`, and `ee/app/views/*` for the old +anchor to make sure you're not breaking an anchor linked from other +documentation nor from the GitLab user interface. If you find the old anchor, be +sure to replace it with the new one. + +Important: + +- Avoid crosslinking documentation to headings unless you need to link to a + specific section of the document. This will avoid breaking anchors in the + future in case the heading is changed. +- If possible, avoid changing headings since they're not only linked internally. + There are various links to GitLab documentation on the internet, such as + tutorials, presentations, StackOverflow posts, and other sources. +- Do not link to `h1` headings. + +Note that, with Kramdown, it is possible to add a custom ID to an HTML element +with Markdown markup, but they _do not_ work in GitLab's `/help`. Therefore, +do not use this option until further notice. + +## Links + +Links are important in GitLab documentation. They allow you to [link instead of +summarizing](#link-instead-of-summarize) to help preserve a [single source of truth](#why-a-single-source-of-truth) +within GitLab documentation. + +We include guidance for links in the following categories: + +- How to set up [anchor links](#anchor-links) for headings. +- How to set up [criteria](#basic-link-criteria) for configuring a link. +- What to set up when [linking to a `help`](../../documentation/index.md#linking-to-help) + page. +- How to set up [links to internal documentation](#links-to-internal-documentation) + for cross-references. +- How to set up [links to external documentation](#links-to-external-documentation) + for authoritative sources. +- When to use [links requiring permissions](#links-requiring-permissions). +- How to set up a [link to a video](#link-to-video). +- How to [include links with version text](#text-for-documentation-requiring-version-text). +- How to [link to specific lines of code](#link-to-specific-lines-of-code) + +### Basic link criteria + +- Use inline link Markdown markup `[Text](https://example.com)`. + It's easier to read, review, and maintain. _Do not_ use `[Text][identifier]`. + +- 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)`. + +### Links to internal documentation + +NOTE: **Note:** +_Internal_ refers to documentation in the same project. When linking to +documentation in separate projects (for example, linking to Omnibus documentation +from GitLab documentation), you must use absolute URLs. + +Do not use absolute URLs like `https://docs.gitlab.com/ee/index.html` to +crosslink to other documentation within the same project. Use relative links to +the file, like `../index.md`. (These are converted to HTML when the site is +rendered.) + +Relative linking enables crosslinks to work: + +- in Review Apps, local previews, and `/help`. +- when working on the documentation locally, so you can verify that they work as + early as possible in the process. +- within the GitLab user interface when browsing doc files in their respective + repositories. For example, the links displayed at + `https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/README.md`. + +To link to internal documentation: + +- Use relative links to Markdown files in the same repository. +- Do not use absolute URLs or URLs from `docs.gitlab.com`. +- Use `../` to navigate to higher-level directories. +- Don't prepend `./` to links to files or directories. +- Don't link relative to root. For example, `/ee/user/gitlab_com/index.md`. + + Don't: + + - `https://docs.gitlab.com/ee/administration/geo/replication/troubleshooting.html` + - `/ee/administration/geo/replication/troubleshooting.md` + - `./troubleshooting.md` + + Do: `../../geo/replication/troubleshooting.md` + +- Always add the file name `file.md` at the end of the link with the `.md` + extension, not `.html`. + + Don't: + + - `../../merge_requests/` + - `../../issues/tags.html` + - `../../issues/tags.html#stages` + + Do: + + - `../../merge_requests/index.md` + - `../../issues/tags.md` + - `../../issues/tags.md#stages` + +NOTE: **Note:** +Using the Markdown extension is necessary for the [`/help`](../index.md#gitlab-help) +section of GitLab. + +### Links to external documentation + +When describing interactions with external software, it's often helpful to +include links to external documentation. When possible, make sure that you're +linking to an [**authoritative** source](#authoritative-sources). For example, +if you're describing a feature in Microsoft's Active Directory, include a link +to official Microsoft documentation. + +### Authoritative sources + +When citing external information, use sources that are written by the people who +created the item or product in question. These sources are the most likely to be +accurate and remain up to date. + +Examples of authoritative sources include: + +- Specifications, such as a [Request for Comments](https://www.ietf.org/standards/rfcs/) + document from the Internet Engineering Task Force. +- Official documentation for a product. For example, if you're setting up an + interface with the Google OAuth 2 authorization server, include a link to + Google's documentation. +- Official documentation for a project. For example, if you're citing NodeJS + functionality, refer directly to [NodeJS documentation](https://nodejs.org/en/docs/). +- Books from an authoritative publisher. + +Examples of sources to avoid include: + +- Personal blog posts. +- Wikipedia. +- Non-trustworthy articles. +- Discussions on forums such as Stack Overflow. +- Documentation from a company that describes another company's product. + +While many of these sources to avoid can help you learn skills and or features, +they can become obsolete quickly. Nobody is obliged to maintain any of these +sites. Therefore, we should avoid using them as reference literature. + +NOTE: **Note:** +Non-authoritative sources are acceptable only if there is no equivalent +authoritative source. Even then, focus on non-authoritative sources that are +extensively cited or peer-reviewed. + +### Links requiring permissions + +Don't link directly to: + +- [Confidential issues](../../../user/project/issues/confidential_issues.md). +- Project features that require [special permissions](../../../user/permissions.md) + to view. + +These will fail for: + +- Those without sufficient permissions. +- Automated link checkers. + +Instead: + +- To reduce confusion, mention in the text that the information is either: + - Contained in a confidential issue. + - Requires special permission to a project to view. +- Provide a link in back ticks (`` ` ``) so that those with access to the issue + can navigate to it. + +Example: + +```markdown +For more information, see the [confidential issue](../../../user/project/issues/confidential_issues.md) `https://gitlab.com/gitlab-org/gitlab-foss/-/issues/<issue_number>`. +``` + +### Link to specific lines of code + +When linking to specific lines within a file, link to a commit instead of to the +branch. Lines of code change through time, therefore, linking to a line by using +the commit link ensures the user lands on the line you're referring to. The +**Permalink** button, which is available when viewing a file within a project, +makes it easy to generate a link to the most recent commit of the given 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).` + +If that linked expression is no longer in that line of the file due to additional +commits, you can still search the file for that query. In this case, update the +document to ensure it links to the most recent version of the file. + +## Navigation + +When documenting navigation through the user interface: + +- Use the exact wording as shown in the UI, including any capital letters as-is. +- Use bold text for navigation items and the char "greater than" (`>`) as a + separator. For example: `Navigate to your project's **Settings > CI/CD**`. +- If there are any expandable menus, make sure to mention that the user needs to + expand the tab to find the settings you're referring to. For example: + `Navigate to your project's **Settings > CI/CD** and expand **General pipelines**`. + +### Navigational elements + +Use the following terms when referring to the main GitLab user interface +elements: + +- **Top menu**: This is the top menu that spans the width of the user interface. + It includes the GitLab logo, search field, counters, and the user's avatar. +- **Left sidebar**: This is the navigation sidebar on the left of the user + interface, specific to the project or group. +- **Right sidebar**: This is the navigation sidebar on the right of the user + interface, specific to the open issue, merge request, or epic. + +## Images + +Images, including screenshots, can help a reader better understand a concept. +However, they can be hard to maintain, and should be used sparingly. + +Before including an image in the documentation, ensure it provides value to the +reader. + +### Capture the image + +Use images to help the reader understand where they are in a process, or how +they need to interact with the application. + +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. +- _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 + a documentation page. For example, if other screenshots include the left + sidebar, include the sidebar in all screenshots. + +### Save the image + +- Save the image with a lowercase file name 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 file name, based on the following 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. + +### Add the image link to content + +The Markdown code for including an image in a document is: +`![Image description which will be the alt tag](img/document_image_title_vX_Y.png)` + +The image description is the alt text for the rendered image on the +documentation site. For accessibility and SEO, use [descriptions](https://webaim.org/techniques/alttext/) +that: + +- Are accurate, succinct, and unique. +- Don't use _image of…_ or _graphic of…_ to describe the image. + +### Compress images + +You should always compress any new images you add to the documentation. One +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. + +GitLab has a [Rake task](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/tasks/pngquant.rake) +that you can use to automate the 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 + been compressed: + + ```shell + bundle exec rake pngquant:lint + ``` + +- Compress all documentation PNG images using `pngquant`: + + ```shell + bundle exec rake pngquant:compress + ``` + +The only caveat is that the task runs on all images under `doc/`, not only the +ones you might have included in a merge request. In that case, you can run the +compress task and only commit the images that are relevant to your merge +request. + +## Videos + +Adding GitLab's existing YouTube video tutorials to the documentation is highly +encouraged, unless the video is outdated. Videos should not replace +documentation, but complement or illustrate it. If content in a video is +fundamental to a feature and its key use cases, but this is not adequately +covered in the documentation, add this detail to the documentation text or +create an issue to review the video and do so. + +Do not upload videos to the product repositories. [Link](#link-to-video) or +[embed](#embed-videos) them instead. + +### Link to video + +To link out to a video, include a YouTube icon so that readers can scan the page +for videos before reading: + +```markdown +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For an overview, see [Video Title](link-to-video). +``` + +You can link any up-to-date video that's useful to the GitLab user. + +### Embed videos + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/472) in GitLab 12.1. + +The [GitLab documentation site](https://docs.gitlab.com) supports embedded +videos. + +You can only embed videos from [GitLab's official YouTube account](https://www.youtube.com/channel/UCnMGQ8QHMAnVIsI3xJrihhg). +For videos from other sources, [link](#link-to-video) them instead. + +In most cases, it is better to [link to video](#link-to-video) instead, because +an embed takes up a lot of space on the page and can be distracting to readers. + +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). +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">`. +1. In YouTube, select **Share**, and then select **Embed**. +1. Copy the `<iframe>` source (`src`) **URL only** + (`https://www.youtube.com/embed/VIDEO-ID`), + and paste it, replacing the content of the `src` field in the + `iframe` tag. + +```html +leave a blank line here +<div class="video-fallback"> + See the video: <a href="https://www.youtube.com/watch?v=MqL6BMOySIQ">Video title</a>. +</div> +<figure class="video-container"> + <iframe src="https://www.youtube.com/embed/MqL6BMOySIQ" frameborder="0" allowfullscreen="true"> </iframe> +</figure> +leave a blank line here +``` + +This is how it renders on the GitLab documentation site: + +<div class="video-fallback"> + See the video: <a href="https://www.youtube.com/watch?v=enMumwvLAug">What is GitLab</a>. +</div> +<figure class="video-container"> + <iframe src="https://www.youtube.com/embed/MqL6BMOySIQ" frameborder="0" allowfullscreen="true"> </iframe> +</figure> + +> Notes: +> +> - The `figure` tag is required for semantic SEO and the `video_container` +class is necessary to make sure the video is responsive and displays on +different mobile devices. +> - The `<div class="video-fallback">` is a fallback necessary for GitLab's +`/help`, as GitLab's Markdown processor does not support iframes. It's hidden on +the documentation site, but will be displayed on GitLab's `/help`. + +## Code blocks + +- Always wrap code added to a sentence in inline code blocks (`` ` ``). + For example, `.gitlab-ci.yml`, `git add .`, `CODEOWNERS`, or `only: [master]`. + File names, commands, entries, and anything that refers to code should be + added to code blocks. To make things easier for the user, always add a full + code block for things that can be useful to copy and paste, as they can do it + with the button on code blocks. +- HTTP methods (`HTTP POST`) and HTTP status codes, both full (`404 File Not Found`) + and abbreviated (`404`), should be wrapped in inline code blocks when used in sentences. + For example: Send a `DELETE` request to delete the runner. Send a `POST` request to create one. +- Add a blank line above and below code blocks. +- When providing a shell command and its output, prefix the shell command with `$` + and leave a blank line between the command and the output. +- When providing a command without output, don't prefix the shell command with `$`. +- If you need to include triple backticks inside a code block, use four backticks + for the codeblock fences instead of three. +- For regular fenced code blocks, always use a highlighting class corresponding to + the language for better readability. Examples: + + ````markdown + ```ruby + Ruby code + ``` + + ```javascript + JavaScript code + ``` + + ```markdown + [Markdown code example](example.md) + ``` + + ```plaintext + Code or text for which no specific highlighting class is available. + ``` + ```` + +Syntax highlighting is required for fenced code blocks added to the GitLab +documentation. Refer to the following table for the most common language classes, +or check the [complete list](https://github.com/rouge-ruby/rouge/wiki/List-of-supported-languages-and-lexers) +of available language classes: + +| Preferred language tags | Language aliases and notes | +|-------------------------|------------------------------------------------------------------------------| +| `asciidoc` | | +| `dockerfile` | Alias: `docker`. | +| `elixir` | | +| `erb` | | +| `golang` | Alias: `go`. | +| `graphql` | | +| `haml` | | +| `html` | | +| `ini` | For some simple config files that are not in TOML format. | +| `javascript` | Alias `js`. | +| `json` | | +| `markdown` | Alias: `md`. | +| `mermaid` | | +| `nginx` | | +| `perl` | | +| `php` | | +| `plaintext` | Examples with no defined language, such as output from shell commands or API calls. If a codeblock has no language, it defaults to `plaintext`. Alias: `text`. | +| `prometheus` | Prometheus configuration examples. | +| `python` | | +| `ruby` | Alias: `rb`. | +| `shell` | Aliases: `bash` or `sh`. | +| `sql` | | +| `toml` | Runner configuration examples, and other TOML-formatted configuration files. | +| `typescript` | Alias: `ts`. | +| `xml` | | +| `yaml` | Alias: `yml`. | + +For a complete reference on code blocks, see the [Kramdown guide](https://about.gitlab.com/handbook/markdown-guide/#code-blocks). + +## GitLab SVG icons + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-docs/-/issues/384) in GitLab 12.7. + +You can use icons from the [GitLab SVG library](https://gitlab-org.gitlab.io/gitlab-svgs/) +directly in the documentation. + +This way, you can achieve a consistent look when writing about interacting with +GitLab user interface elements. + +Usage examples: + +- Icon with default size (16px): `**{icon-name}**` + + Example: `**{tanuki}**` renders as: **{tanuki}**. +- Icon with custom size: `**{icon-name, size}**` + + Available sizes (in px): 8, 10, 12, 14, 16, 18, 24, 32, 48, and 72 + + Example: `**{tanuki, 24}**` renders as: **{tanuki, 24}**. +- Icon with custom size and class: `**{icon-name, size, class-name}**`. + + You can access any class available to this element in GitLab documentation CSS. + + Example with `float-right`, a + [Bootstrap utility class](https://getbootstrap.com/docs/4.4/utilities/float/): + `**{tanuki, 32, float-right}**` renders as: **{tanuki, 32, float-right}** + +### When to use icons + +Icons should be used sparingly, and only in ways that aid and do not hinder the +readability of the text. + +For example, the following adds little to the accompanying text: + +```markdown +1. Go to **{home}** **Project overview > Details** +``` + +1. Go to **{home}** **Project overview > Details** + +However, the following might help the reader connect the text to the user +interface: + +```markdown +| Section | Description | +|:-------------------------|:----------------------------------------------------------------------------------------------------------------------------| +| **{overview}** Overview | View your GitLab Dashboard, and administer projects, users, groups, jobs, runners, and Gitaly servers. | +| **{monitor}** Monitoring | View GitLab system information, and information on background jobs, logs, health checks, requests profiles, and audit logs. | +| **{messages}** Messages | Send and manage broadcast messages for your users. | +``` + +| Section | Description | +|:-------------------------|:----------------------------------------------------------------------------------------------------------------------------| +| **{overview}** Overview | View your GitLab Dashboard, and administer projects, users, groups, jobs, runners, and Gitaly servers. | +| **{monitor}** Monitoring | View GitLab system information, and information on background jobs, logs, health checks, requests profiles, and audit logs. | +| **{messages}** Messages | Send and manage broadcast messages for your users. | + +Use an icon when you find yourself having to describe an interface element. For +example: + +- Do: Select the Admin Area icon ( **{admin}** ). +- Don't: Select the Admin Area icon (the wrench icon). + +## Alert boxes + +When you need to call special attention to particular sentences, use the +following markup to create highlighted alert boxes. + +Alert boxes work for one paragraph only. Multiple paragraphs, lists, and headers +won't render correctly. For multiple lines, use [blockquotes](#blockquotes) +instead. + +Alert boxes render only on the GitLab documentation site (<https://docs.gitlab.com>). +In the GitLab product help, alert boxes appear as plain Markdown text. + +These alert boxes are used in the GitLab documentation. These aren't strict +guidelines, but for consistency you should try to use these values: + +| Color | Markup | Default keyword | Alternative keywords | +|--------|------------|-----------------|----------------------------------------------------------------------| +| Blue | `NOTE:` | `**Note:**` | | +| Yellow | `CAUTION:` | `**Caution:**` | `**Warning:**`, `**Important:**` | +| Red | `DANGER:` | `**Danger:**` | `**Warning:**`, `**Important:**`, `**Deprecated:**`, `**Required:**` | +| Green | `TIP:` | `**Tip:**` | | + +### Note + +Notes indicate additional information that's of special use to the reader. +Notes are most effective when used _sparingly_. + +Try to avoid them. Too many notes can impact the scannability of a topic and +create an overly busy page. + +Instead of adding a note, try one of these alternatives: + +- Re-write the sentence as part of the most-relevant paragraph. +- Put the information into its own standalone paragraph. +- Put the content under a new subheading that introduces the topic, which makes + it more visible. + +If you must use a note, use the following formatting: + +```markdown +NOTE: **Note:** +This is something to note. +``` + +How it renders on the GitLab documentation site: + +NOTE: **Note:** +This is something to note. + +### Tip + +```markdown +TIP: **Tip:** +This is a tip. +``` + +How it renders on the GitLab documentation site: + +TIP: **Tip:** +This is a tip. + +### Caution + +```markdown +CAUTION: **Caution:** +This is something to be cautious about. +``` + +How it renders on the GitLab documentation site: + +CAUTION: **Caution:** +This is something to be cautious about. + +### Danger + +```markdown +DANGER: **Warning:** +This is a breaking change, a bug, or something very important to note. +``` + +How it renders on the GitLab documentation site: + +DANGER: **Warning:** +This is a breaking change, a bug, or something very important to note. + +## Blockquotes + +For highlighting a text within a blue blockquote, use this format: + +```markdown +> This is a blockquote. +``` + +which renders on the [GitLab documentation site](https://docs.gitlab.com) as: + +> This is a blockquote. + +If the text spans across multiple lines it's OK to split the line. + +For multiple paragraphs, use the symbol `>` before every line: + +```markdown +> This is the first paragraph. +> +> This is the second paragraph. +> +> - This is a list item +> - Second item in the list +``` + +Which renders to: + +> This is the first paragraph. +> +> This is the second paragraph. +> +> - This is a list item +> - Second item in the list + +## Terms + +To maintain consistency through GitLab documentation, the following guides +documentation authors on agreed styles and usage of terms. + +### Merge requests (MRs) + +Merge requests allow you to exchange changes you made to source code and +collaborate with other people on the same project. You'll see this term used in +the following ways: + +- Use lowercase _merge requests_ regardless of whether referring to the feature + or individual merge requests. + +As noted in the GitLab [Writing Style Guidelines](https://about.gitlab.com/handbook/communication/#writing-style-guidelines), +if you use the _MR_ acronym, expand it at least once per document page. +Typically, the first use would be phrased as _merge request (MR)_ with subsequent +instances being _MR_. + +Examples: + +- "We prefer GitLab merge requests". +- "Open a merge request to fix a broken link". +- "After you open a merge request (MR), submit your MR for review and approval". + +### Describe UI elements + +The following are styles to follow when describing user interface elements in an +application: + +- For elements with a visible label, use that label in bold with matching case. + For example, `the **Cancel** button`. +- For elements with a tooltip or hover label, use that label in bold with + matching case. For example, `the **Add status emoji** button`. + +### Verbs for UI elements + +The following are recommended 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" | + +### Other Verbs + +| Recommended | Used for | Replaces | +|:------------|:--------------------------------|:----------------------| +| _go to_ | making a browser go to location | "navigate to", "open" | + +## GitLab versions and tiers + +Tagged and released versions of GitLab documentation are available: + +- In the [documentation archives](https://docs.gitlab.com/archives/). +- At the `/help` URL for any GitLab installation. + +The version introducing a new feature is added to the top of the topic in the +documentation to provide a link back to how the feature was developed. + +TIP: **Tip:** +Whenever you have documentation related to the `gitlab.rb` file, you're working +with a self-managed installation. The section or page is therefore likely to +apply only to self-managed instances. If so, the relevant "`TIER` ONLY" +[Product badge](#product-badges) should be included at the highest applicable +heading level. + +### Text for documentation requiring version text + +When a feature is new or updated, you can add version information as a bulleted +item in the **Version history**, or as an inline reference with related text. + +#### Version text in the **Version History** + +If all content in a section is related, add version text following the header for +the section. Each entry should be on a single line. To render correctly, it must be on its +own line and surrounded by blank lines. + +Features should declare the GitLab version that introduced a feature in a blockquote +following the header: + +```markdown +## Feature name + +> Introduced in GitLab 11.3. + +This feature does something. +``` + +Whenever possible, version text should have a link to the _completed_ issue, +merge request, or epic that introduced the feature. An issue is preferred over +a merge request, and a merge request is preferred over an epic. For example: + +```markdown +> [Introduced](<link-to-issue>) in GitLab 11.3. +``` + +If the feature is only available in GitLab Enterprise Edition, mention +the [paid tier](https://about.gitlab.com/handbook/marketing/strategic-marketing/tiers/) +the feature is available in: + +```markdown +> [Introduced](<link-to-issue>) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.3. +``` + +If listing information for multiple version as a feature evolves, add the +information to a block-quoted bullet list. For example: + +```markdown +> - [Introduced](<link-to-issue>) in GitLab 11.3. +> - Enabled by default in GitLab 11.4. +``` + +If a feature is moved to another tier: + +```markdown +> - [Introduced](<link-to-issue>) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.5. +> - [Moved](<link-to-issue>) to [GitLab Starter](https://about.gitlab.com/pricing/) in 11.8. +> - [Moved](<link-to-issue>) to GitLab Core in 12.0. +``` + +If a feature is deprecated, include a link to a replacement (when available): + +```markdown +> - [Deprecated](<link-to-issue>) in GitLab 11.3. Replaced by [meaningful text](<link-to-appropriate-documentation>). +``` + +You can also describe the replacement in surrounding text, if available. + +If the deprecation is not obvious in existing text, you may want to include a +warning such as: + +```markdown +DANGER: **Deprecated:** +This feature was [deprecated](link-to-issue) in GitLab 12.3 +and replaced by [Feature name](link-to-feature-documentation). +``` + +#### Inline version text + +If you're adding content to an existing topic, you can add version information +inline with the existing text. + +In this case, add `([introduced/deprecated](<link-to-issue>) in GitLab X.X)`. +If applicable, include the paid tier: `([introduced/deprecated](<link-to-issue>) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.4)` + +Including the issue link is encouraged, but isn't a requirement. For example: + +```markdown +The voting strategy (in GitLab 13.4 and later) requires +the primary and secondary voters to agree. +``` + +#### End-of-life for features or products + +Whenever a feature or product enters the end-of-life process, indicate its +status by using the `Danger` [alert](#alert-boxes) with the `**Important**` +keyword directly below the feature or product's header (which can include H1 +page titles). Link to the deprecation and removal issues, if possible. + +For example: + +```markdown +DANGER: **Important:** +This feature is in its end-of-life process. It is [deprecated](link-to-issue) +for use in GitLab X.X, and is planned for [removal](link-to-issue) in GitLab X.X. +``` + +### Versions in the past or future + +When describing functionality available in past or future versions, use: + +- _Earlier_, and not _older_ or _before_. +- _Later_, and not _newer_ or _after_. + +For example: + +- Available in GitLab 12.3 and earlier. +- Available in GitLab 12.4 and later. +- In GitLab 11.4 and earlier, ... +- In GitLab 10.6 and later, ... + +### Importance of referencing GitLab versions and tiers + +Mentioning GitLab versions and tiers is important to all users and contributors +to quickly have access to the issue or merge request that introduced the change. +Also, they can know what features they have in their GitLab +instance and version, given that the note has some key information. + +`[Introduced](link-to-issue) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.7` +links to the issue that introduced the feature, says which GitLab tier it +belongs to, says the GitLab version that it became available in, and links to +the pricing page in case the user wants to upgrade to a paid tier to use that +feature. + +For example, if you're a regular user and you're looking at the documentation +for a feature you haven't used before, you can immediately see if that feature +is available to you or not. Alternatively, if you've been using a certain +feature for a long time and it changed in some way, it's important to be able to +determine when it changed and what's new in that feature. + +This is even more important as we don't have a perfect process for shipping +documentation. Unfortunately, we still see features without documentation, and +documentation without features. So, for now, we cannot rely 100% on the +documentation site versions. + +Over time, version text will reference a progressively older version of GitLab. +In cases where version text refers to versions of GitLab four or more major +versions back, you can consider removing the text if it's irrelevant or confusing. + +For example, if the current major version is 12.x, version text referencing +versions of GitLab 8.x and older are candidates for removal if necessary for +clearer or cleaner documentation. + +## Products and features + +Refer to the information in this section when describing products and features +within the GitLab product documentation. + +### Avoid line breaks in names + +When entering a product or feature name that includes a space (such as +GitLab Community Edition) or even other companies' products (such as +Amazon Web Services), be sure to not split the product or feature name across +lines with an inserted line break. Splitting product or feature names across +lines makes searching for these items more difficult, and can cause problems if +names change. + +For example, the following Markdown content is _not_ formatted correctly: + +```markdown +When entering a product or feature name that includes a space (such as GitLab +Community Edition), don't split the product or feature name across lines. +``` + +Instead, it should appear similar to the following: + +```markdown +When entering a product or feature name that includes a space (such as +GitLab Community Edition), don't split the product or feature name across lines. +``` + +### Product badges + +When a feature is available in paid tiers, add the corresponding tier to the +header or other page element according to the feature's availability: + +| Tier in which feature is available | Tier markup | +|:-----------------------------------------------------------------------|:----------------------| +| GitLab Core and GitLab.com Free, and their higher tiers | `**(CORE)**` | +| GitLab Starter and GitLab.com Bronze, and their higher tiers | `**(STARTER)**` | +| GitLab Premium and GitLab.com Silver, and their higher tiers | `**(PREMIUM)**` | +| GitLab Ultimate and GitLab.com Gold | `**(ULTIMATE)**` | +| _Only_ GitLab Core and higher tiers (no GitLab.com-based tiers) | `**(CORE ONLY)**` | +| _Only_ GitLab Starter and higher tiers (no GitLab.com-based tiers) | `**(STARTER ONLY)**` | +| _Only_ GitLab Premium and higher tiers (no GitLab.com-based tiers) | `**(PREMIUM ONLY)**` | +| _Only_ GitLab Ultimate (no GitLab.com-based tiers) | `**(ULTIMATE ONLY)**` | +| _Only_ GitLab.com Free and higher tiers (no self-managed instances) | `**(FREE ONLY)**` | +| _Only_ GitLab.com Bronze and higher tiers (no self-managed instances) | `**(BRONZE ONLY)**` | +| _Only_ GitLab.com Silver and higher tiers (no self-managed instances) | `**(SILVER ONLY)**` | +| _Only_ GitLab.com Gold (no self-managed instances) | `**(GOLD ONLY)**` | + +For clarity, all page title headers (H1s) must be have a tier markup for the +lowest tier that has information on the documentation page. + +If sections of a page apply to higher tier levels, they can be separately +labeled with their own tier markup. + +#### Product badge display behavior + +When using the tier markup with headers, the documentation page will display the +full tier badge with the header line. + +You can also use the tier markup with paragraphs, list items, and table cells. +For these cases, the tier mention will be represented by an orange info icon +**{information}** that will display the tiers when visitors point to the icon. +For example: + +- `**(STARTER)**` displays as **(STARTER)** +- `**(STARTER ONLY)**` displays as **(STARTER ONLY)** +- `**(SILVER ONLY)**` displays as **(SILVER ONLY)** + +#### How it works + +Introduced by [!244](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/244), +the special markup `**(STARTER)**` will generate a `span` element to trigger the +badges and tooltips (`<span class="badge-trigger starter">`). When the keyword +_only_ is added, the corresponding GitLab.com badge will not be displayed. + +## Specific sections + +Certain styles should be applied to specific sections. Styles for specific +sections are outlined in this section. + +### GitLab restart + +There are many cases that a restart/reconfigure of GitLab is required. To avoid +duplication, link to the special document that can be found in +[`doc/administration/restart_gitlab.md`](../../../administration/restart_gitlab.md). +Usually the text will read like: + +```markdown +Save the file and [reconfigure GitLab](../../../administration/restart_gitlab.md) +for the changes to take effect. +``` + +If the document you are editing resides in a place other than the GitLab CE/EE +`doc/` directory, instead of the relative link, use the full path: +`https://docs.gitlab.com/ee/administration/restart_gitlab.html`. Replace +`reconfigure` with `restart` where appropriate. + +### Installation guide + +**Ruby:** +In [step 2 of the installation guide](../../../install/installation.md#2-ruby), +we install Ruby from source. Whenever there is a new version that needs to +be updated, remember to change it throughout the codeblock and also replace +the sha256sum (it can be found in the [downloads page](https://www.ruby-lang.org/en/downloads/) +of the Ruby website). + +### Configuration documentation for source and Omnibus installations + +GitLab currently officially supports two installation methods: installations +from source and Omnibus packages installations. + +Whenever there's a setting that's configurable for both installation methods, +the preference is to document it in the CE documentation to avoid duplication. + +Configuration settings include: + +- Settings that touch configuration files in `config/`. +- NGINX settings and settings in `lib/support/` in general. + +When you document a list of steps, it may entail editing the configuration file +and reconfiguring or restarting GitLab. In that case, use these styles: + +````markdown +**For Omnibus installations** + +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + external_url "https://gitlab.example.com" + ``` + +1. Save the file and [reconfigure](path/to/administration/restart_gitlab.md#omnibus-gitlab-reconfigure) + GitLab for the changes to take effect. + +--- + +**For installations from source** + +1. Edit `config/gitlab.yml`: + + ```yaml + gitlab: + host: "gitlab.example.com" + ``` + +1. Save the file and [restart](path/to/administration/restart_gitlab.md#installations-from-source) + GitLab for the changes to take effect. +```` + +In this case: + +- Before each step list the installation method is declared in bold. +- Three dashes (`---`) are used to create a horizontal line and separate the two + methods. +- The code blocks are indented one or more spaces under the list item to render + correctly. +- Different highlighting languages are used for each config in the code block. +- The [GitLab Restart](#gitlab-restart) section is used to explain a required + restart or reconfigure of GitLab. + +### Troubleshooting + +For troubleshooting sections, you should provide as much context as possible so +users can identify the problem they are facing and resolve it on their own. You +can facilitate this by making sure the troubleshooting content addresses: + +1. The problem the user needs to solve. +1. How the user can confirm they have the problem. +1. Steps the user can take towards resolution of the problem. + +If the contents of each category can be summarized in one line and a list of +steps aren't required, consider setting up a [table](#tables) with headers of +_Problem_ \| _Cause_ \| _Solution_ (or _Workaround_ if the fix is temporary), or +_Error message_ \| _Solution_. + +## Feature flags + +Learn how to [document features deployed behind flags](../feature_flags.md). For +guidance on developing GitLab with feature flags, see [Feature flags in development of GitLab](../../feature_flags/index.md). diff --git a/doc/development/documentation/testing.md b/doc/development/documentation/testing.md new file mode 100644 index 00000000000..043da38d207 --- /dev/null +++ b/doc/development/documentation/testing.md @@ -0,0 +1,292 @@ +--- +stage: none +group: Documentation Guidelines +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +description: Learn how to contribute to GitLab Documentation. +--- + +# Documentation testing + +We treat documentation as code, and so use tests in our CI pipeline to maintain the +standards and quality of the docs. The current tests, which run in CI jobs when a +merge request with new or changed docs is submitted, are: + +- [`docs lint`](https://gitlab.com/gitlab-org/gitlab/-/blob/0b562014f7b71f98540e682c8d662275f0011f2f/.gitlab/ci/docs.gitlab-ci.yml#L41): + Runs several tests on the content of the docs themselves: + - [`lint-doc.sh` script](https://gitlab.com/gitlab-org/gitlab/blob/master/scripts/lint-doc.sh) + runs the following checks and linters: + - All cURL examples use the long flags (ex: `--header`, not `-H`). + - The `CHANGELOG.md` does not contain duplicate versions. + - No files in `doc/` are executable. + - No new `README.md` was added. + - [markdownlint](#markdownlint). + - [Vale](#vale). + - Nanoc tests: + - [`internal_links`](https://gitlab.com/gitlab-org/gitlab/-/blob/0b562014f7b71f98540e682c8d662275f0011f2f/.gitlab/ci/docs.gitlab-ci.yml#L58) + checks that all internal links (ex: `[link](../index.md)`) are valid. + - [`internal_anchors`](https://gitlab.com/gitlab-org/gitlab/-/blob/0b562014f7b71f98540e682c8d662275f0011f2f/.gitlab/ci/docs.gitlab-ci.yml#L60) + checks that all internal anchors (ex: `[link](../index.md#internal_anchor)`) + are valid. + - [`ui-docs-links lint`](https://gitlab.com/gitlab-org/gitlab/-/blob/0b562014f7b71f98540e682c8d662275f0011f2f/.gitlab/ci/docs.gitlab-ci.yml#L62) + checks that all links to docs from UI elements (`app/views` files, for example) + are linking to valid docs and anchors. + +## Run tests locally + +Apart from [previewing your changes locally](index.md#previewing-the-changes-live), you can also run all lint checks +and Nanoc tests locally. + +### Lint checks + +Lint checks are performed by the [`lint-doc.sh`](https://gitlab.com/gitlab-org/gitlab/blob/master/scripts/lint-doc.sh) +script and can be executed as follows: + +1. Navigate to the `gitlab` directory. +1. Run: + + ```shell + MD_DOC_PATH=path/to/my_doc.md scripts/lint-doc.sh + ``` + +Where `MD_DOC_PATH` points to the file or directory you would like to run lint checks for. +If you omit it completely, it defaults to the `doc/` directory. +The output should be similar to: + +```plaintext +=> Linting documents at path /path/to/gitlab as <user>... +=> Checking for cURL short options... +=> Checking for CHANGELOG.md duplicate entries... +=> Checking /path/to/gitlab/doc for executable permissions... +=> Checking for new README.md files... +=> Linting markdown style... +=> Linting prose... +✔ 0 errors, 0 warnings and 0 suggestions in 1 file. +✔ Linting passed +``` + +This requires you to either: + +- Have the required lint tools installed on your machine. +- A working Docker installation, in which case an image with these tools pre-installed is used. + +### Nanoc tests + +To execute Nanoc tests locally: + +1. Navigate to the [`gitlab-docs`](https://gitlab.com/gitlab-org/gitlab-docs) directory. +1. Run: + + ```shell + # Check for broken internal links + bundle exec nanoc check internal_links + + # Check for broken external links (might take a lot of time to complete). + # This test is set to be allowed to fail and is run only in the gitlab-docs project CI + bundle exec nanoc check internal_anchors + ``` + +### `ui-docs-links` test + +The `ui-docs-links lint` job uses `haml-lint` to test that all links to docs from +UI elements (`app/views` files, for example) are linking to valid docs and anchors. + +To run the `ui-docs-links` test locally: + +1. Open the `gitlab` directory in a terminal window. +1. Run: + + ```shell + bundle exec haml-lint -i DocumentationLinks + ``` + +If you receive an error the first time you run this test, run `bundle install`, which +installs GitLab's dependencies, and try again. + +If you don't want to install all of GitLab's dependencies to test the links, you can: + +1. Open the `gitlab` directory in a terminal window. +1. Install `haml-lint`: + + ```shell + gem install haml_lint + ``` + +1. Run: + + ```shell + haml-lint -i DocumentationLinks + ``` + +If you manually install `haml-lint` with this process, it does not update automatically +and you should make sure your version matches the version used by GitLab. + +## Local linters + +To help adhere to the [documentation style guidelines](styleguide/index.md), and improve the content +added to documentation, [install documentation linters](#install-linters) and +[integrate them with your code editor](#configure-editors). + +At GitLab, we mostly use: + +- [markdownlint](#markdownlint) +- [Vale](#vale) + +### markdownlint + +[markdownlint](https://github.com/DavidAnson/markdownlint) checks that Markdown syntax follows +[certain rules](https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#rules), and is +used by the `docs-lint` test. + +Our [Documentation Style Guide](styleguide/index.md#markdown) and +[Markdown Guide](https://about.gitlab.com/handbook/markdown-guide/) elaborate on which choices must +be made when selecting Markdown syntax for GitLab documentation. This tool helps catch deviations +from those guidelines. + +markdownlint configuration is found in the following projects: + +- [`gitlab`](https://gitlab.com/gitlab-org/gitlab/blob/master/.markdownlint.json) +- [`gitlab-runner`](https://gitlab.com/gitlab-org/gitlab-runner/blob/master/.markdownlint.json) +- [`omnibus-gitlab`](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/.markdownlint.json) +- [`charts`](https://gitlab.com/gitlab-org/charts/gitlab/-/blob/master/.markdownlint.json) +- [`gitlab-development-kit`](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/master/.markdownlint.json) + +This configuration is also used within build pipelines. + +You can use markdownlint: + +- [On the command line](https://github.com/igorshubovych/markdownlint-cli#markdownlint-cli--). +- [Within a code editor](#configure-editors). +- [In a `pre-push` hook](#configure-pre-push-hooks). + +### Vale + +[Vale](https://errata-ai.gitbook.io/vale/) is a grammar, style, and word usage linter for the +English language. Vale's configuration is stored in the +[`.vale.ini`](https://gitlab.com/gitlab-org/gitlab/blob/master/.vale.ini) file located in the root +directory of projects. + +Vale supports creating [custom tests](https://errata-ai.github.io/vale/styles/) that extend any of +several types of checks, which we store in the `.linting/vale/styles/gitlab` directory within the +documentation directory of projects. + +Vale configuration is found in the following projects: + +- [`gitlab`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc/.vale/gitlab) +- [`gitlab-runner`](https://gitlab.com/gitlab-org/gitlab-runner/-/tree/master/docs/.vale/gitlab) +- [`omnibus-gitlab`](https://gitlab.com/gitlab-org/omnibus-gitlab/-/tree/master/doc/.vale/gitlab) +- [`charts`](https://gitlab.com/gitlab-org/charts/gitlab/-/tree/master/doc/.vale/gitlab) +- [`gitlab-development-kit`](https://gitlab.com/gitlab-org/gitlab-development-kit/-/tree/master/doc/.vale/gitlab) + +This configuration is also used within build pipelines. + +You can use Vale: + +- [On the command line](https://errata-ai.gitbook.io/vale/getting-started/usage). +- [Within a code editor](#configure-editors). +- [In a Git hook](#configure-pre-push-hooks). Vale only reports errors in the Git hook (the same + configuration as the CI/CD pipelines), and does not report suggestions or warnings. + +### Install linters + +At a minimum, install [markdownlint](#markdownlint) and [Vale](#vale) to match the checks run in +build pipelines: + +1. Install `markdownlint-cli`, using either: + + - `npm`: + + ```shell + npm install -g markdownlint-cli + ``` + + - `yarn`: + + ```shell + yarn global add markdownlint-cli + ``` + + We recommend installing the version of `markdownlint-cli` currently used in the documentation + linting [Docker image](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/master/.gitlab-ci.yml#L420). + +1. Install [`vale`](https://github.com/errata-ai/vale/releases). For example, to install using + `brew` for macOS, run: + + ```shell + brew install vale + ``` + + We recommend installing the version of Vale currently used in the documentation linting + [Docker image](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/master/.gitlab-ci.yml#L419). + +In addition to using markdownlint and Vale at the command line, these tools can be +[integrated with your code editor](#configure-editors). + +### Configure editors + +To configure markdownlint within your editor, install one of the following as appropriate: + +- [Sublime Text](https://packagecontrol.io/packages/SublimeLinter-contrib-markdownlint) +- [Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) +- [Atom](https://atom.io/packages/linter-node-markdownlint) +- [Vim](https://github.com/dense-analysis/ale) + +To configure Vale within your editor, install one of the following as appropriate: + +- The Sublime Text [`SublimeLinter-contrib-vale` plugin](https://packagecontrol.io/packages/SublimeLinter-contrib-vale). +- The Visual Studio Code [`errata-ai.vale-server` extension](https://marketplace.visualstudio.com/items?itemName=errata-ai.vale-server). + You don't need Vale Server to use the plugin. You can configure the plugin to + [display only a subset of alerts](#show-subset-of-vale-alerts). +- [Vim](https://github.com/dense-analysis/ale). + +We don't use [Vale Server](https://errata-ai.github.io/vale/#using-vale-with-a-text-editor-or-another-third-party-application). + +### Configure pre-push hooks + +Git [pre-push hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks) allow Git users to: + +- Run tests or other processes before pushing a branch. +- Avoid pushing a branch if failures occur with these tests. + +[`lefthook`](https://github.com/Arkweid/lefthook) is a Git hooks manager, making configuring, +installing, and removing Git hooks easy. + +Configuration for `lefthook` is available in the [`lefthook.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lefthook.yml) +file for the [`gitlab`](https://gitlab.com/gitlab-org/gitlab) project. + +To set up `lefthook` for documentation linting, see +[Pre-push static analysis](../contributing/style_guides.md#pre-push-static-analysis). + +### Show subset of Vale alerts + +You can set Visual Studio Code to display only a subset of Vale alerts when viewing files: + +1. Go to **Preferences > Settings > Extensions > Vale**. +1. In **Vale CLI: Min Alert Level**, select the minimum alert level you want displayed in files. + +To display only a subset of Vale alerts when running Vale from the command line, use +the `--minAlertLevel` flag, which accepts `error`, `warning`, or `suggestion`. Combine it with `--config` +to point to the configuration file within the project, if needed: + +```shell +vale --config .vale.ini --minAlertLevel error doc/**/*.md +``` + +Omit the flag to display all alerts, including `suggestion` level alerts. + +### Disable Vale tests + +You can disable a specific Vale linting rule or all Vale linting rules for any portion of a +document: + +- To disable a specific rule, add a `<!-- vale gitlab.rulename = NO -->` tag before the text, and a + `<!-- vale gitlab.rulename = YES -->` tag after the text, replacing `rulename` with the filename + of a test in the + [GitLab styles](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc/.linting/vale/styles/gitlab) + directory. +- To disable all Vale linting rules, add a `<!-- vale off -->` tag before the text, and a + `<!-- vale on -->` tag after the text. + +Whenever possible, exclude only the problematic rule and line(s). + +For more information, see +[Vale's documentation](https://errata-ai.gitbook.io/vale/getting-started/markup#markup-based-configuration). diff --git a/doc/development/documentation/workflow.md b/doc/development/documentation/workflow.md index 488c71a6328..9bc80116d25 100644 --- a/doc/development/documentation/workflow.md +++ b/doc/development/documentation/workflow.md @@ -1,10 +1,15 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Documentation process The process for creating and maintaining GitLab product documentation allows anyone to contribute a merge request or create an issue for GitLab's documentation. -NOTE: **Note:** Documentation updates relating to new features or feature enhancements must use the [feature workflow process](https://about.gitlab.com/handbook/engineering/ux/technical-writing/workflow/#for-a-product-change) described in the GitLab Handbook. @@ -53,7 +58,7 @@ To update GitLab documentation: [GitLab Documentation guidelines](index.md) page. 1. Follow the described standards and processes listed on the page, including: - The [Structure and template](structure.md) page. - - The [Style Guide](styleguide.md). + - The [Style Guide](styleguide/index.md). - The [Markdown Guide](https://about.gitlab.com/handbook/markdown-guide/). 1. Follow GitLab's [Merge Request Guidelines](../contributing/merge_request_workflow.md#merge-request-guidelines). @@ -82,7 +87,7 @@ Anyone with Maintainer access to the relevant GitLab project can merge documenta Maintainers must make a good-faith effort to ensure that the content: - Is clear and sufficiently easy for the intended audience to navigate and understand. -- Meets the [Documentation Guidelines](index.md) and [Style Guide](styleguide.md). +- Meets the [Documentation Guidelines](index.md) and [Style Guide](styleguide/index.md). If the author or reviewer has any questions, they can mention the writer who is assigned to the relevant [DevOps stage group](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments). @@ -149,16 +154,15 @@ Remember: Ensure the following if skipping an initial Technical Writer review: -- That [product badges](styleguide.md#product-badges) are applied. -- That the GitLab [version](styleguide.md#text-for-documentation-requiring-version-text) that +- That [product badges](styleguide/index.md#product-badges) are applied. +- That the GitLab [version](styleguide/index.md#text-for-documentation-requiring-version-text) that introduced the feature has been included. - That 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: - - For [directories and files](styleguide.md#work-with-directories-and-files). - - For [images](styleguide.md#images). + - For [directories and files](styleguide/index.md#work-with-directories-and-files). + - For [images](styleguide/index.md#images). -NOTE: **Note:** Merge requests that change the location of documentation must always be reviewed by a Technical Writer prior to merging. |