diff options
Diffstat (limited to 'doc/development/documentation')
12 files changed, 268 insertions, 118 deletions
diff --git a/doc/development/documentation/graphql_styleguide.md b/doc/development/documentation/graphql_styleguide.md index d658794f7e0..5acc8bda6a6 100644 --- a/doc/development/documentation/graphql_styleguide.md +++ b/doc/development/documentation/graphql_styleguide.md @@ -78,7 +78,7 @@ You should include a link for your new document in the global navigation (the li left side of the documentation website). To do so, open a second MR, against the [GitLab documentation repository](https://gitlab.com/gitlab-org/gitlab-docs/). -We store our global navigation in the [`default-nav.yaml`](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/master/content/_data/default-nav.yaml) file, in the +We store our global navigation in the [`navigation.yaml`](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/content/_data/navigation.yaml) file, in the `content/_data` subdirectory. You can find the GraphQL section under the following line: diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index 05aa003d89e..12a1912dd25 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -27,8 +27,8 @@ The source of the documentation exists within the codebase of each GitLab applic | Project | Path | | --- | --- | -| [GitLab](https://gitlab.com/gitlab-org/gitlab/) | [`/doc`](https://gitlab.com/gitlab-org/gitlab/tree/master/doc) | -| [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner/) | [`/docs`](https://gitlab.com/gitlab-org/gitlab-runner/tree/master/docs) | +| [GitLab](https://gitlab.com/gitlab-org/gitlab/) | [`/doc`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc) | +| [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner/) | [`/docs`](https://gitlab.com/gitlab-org/gitlab-runner/-/tree/main/docs) | | [Omnibus GitLab](https://gitlab.com/gitlab-org/omnibus-gitlab/) | [`/doc`](https://gitlab.com/gitlab-org/omnibus-gitlab/tree/master/doc) | | [Charts](https://gitlab.com/gitlab-org/charts/gitlab) | [`/doc`](https://gitlab.com/gitlab-org/charts/gitlab/tree/master/doc) | @@ -156,7 +156,7 @@ Nanoc layout), which is displayed at the top of the page if defined: - `reading_time`: If you want to add an indication of the approximate reading time of a page, you can set `reading_time` to `true`. This uses a simple - [algorithm](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/master/lib/helpers/reading_time.rb) + [algorithm](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/lib/helpers/reading_time.rb) to calculate the reading time based on the number of words. ## Move or rename a page @@ -177,8 +177,8 @@ There are two types of redirects: - [GitLab Pages redirects](../../user/project/pages/redirects.md), for users who view the docs on [`docs.gitlab.com`](https://docs.gitlab.com). -The Technical Writing team manages the [process](https://gitlab.com/gitlab-org/technical-writing/-/blob/master/.gitlab/issue_templates/tw-monthly-tasks.md) -to regularly update the [`redirects.yaml`](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/master/content/_data/redirects.yaml) +The Technical Writing team manages the [process](https://gitlab.com/gitlab-org/technical-writing/-/blob/main/.gitlab/issue_templates/tw-monthly-tasks.md) +to regularly update the [`redirects.yaml`](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/content/_data/redirects.yaml) file. To add a redirect: @@ -229,6 +229,7 @@ To add a redirect: ```markdown --- redirect_to: '../newpath/to/file/index.md' + remove_date: 'YYYY-MM-DD' --- This document was moved to [another location](../path/to/file/index.md). @@ -295,7 +296,7 @@ Before getting started, make sure you read the introductory section "[contributing to docs](#contributing-to-docs)" above and the [documentation workflow](workflow.md). -- Use the current [merge request description template](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/merge_request_templates/Documentation.md) +- Use the current [merge request description template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/merge_request_templates/Documentation.md) - Label the MR `Documentation` (can only be done by people with `developer` access, for example, GitLab team members) - Assign the correct milestone per note below (can only be done by people with `developer` access, for example, GitLab team members) @@ -316,7 +317,8 @@ it increases the work of the release managers. Every GitLab instance includes the documentation, which is available at `/help` (`https://gitlab.example.com/help`). For example, <https://gitlab.com/help>. -The documentation available online on <https://docs.gitlab.com> is deployed every four hours from the `master` branch of GitLab, Omnibus, and Runner. Therefore, +The documentation available online on <https://docs.gitlab.com> is deployed every +four hours from the `main` branch of GitLab, Omnibus, and Runner. Therefore, after a merge request gets merged, it is available online on the same day. However, it's shipped (and available on `/help`) within the milestone assigned to the MR. @@ -392,7 +394,7 @@ This is preferred over static paths, as the helper also works on instances insta ### GitLab `/help` tests -Several [RSpec tests](https://gitlab.com/gitlab-org/gitlab/blob/master/spec/features/help_pages_spec.rb) +Several [RSpec tests](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/features/help_pages_spec.rb) are run to ensure GitLab documentation renders and works correctly. In particular, that [main docs landing page](../../README.md) works correctly from `/help`. For example, [GitLab.com's `/help`](https://gitlab.com/help). @@ -411,7 +413,7 @@ on how the left-side navigation menu is built and updated. NOTE: To preview your changes to documentation locally, follow this -[development guide](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/README.md#development-when-contributing-to-gitlab-documentation) or [these instructions for GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/main/doc/howto/gitlab_docs.md). +[development guide](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/README.md#development-when-contributing-to-gitlab-documentation) or [these instructions for GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/main/doc/howto/gitlab_docs.md). The live preview is currently enabled for the following projects: @@ -458,9 +460,9 @@ In case the review app URL returns 404, follow these steps to debug: If you want to know the in-depth details, here's what's really happening: 1. You manually run the `review-docs-deploy` job in a merge request. -1. The job runs the [`scripts/trigger-build`](https://gitlab.com/gitlab-org/gitlab/blob/master/scripts/trigger-build) +1. The job runs the [`scripts/trigger-build`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/scripts/trigger-build) script with the `docs deploy` flag, which triggers the "Triggered from `gitlab-org/gitlab` 'review-docs-deploy' job" - pipeline trigger in the `gitlab-org/gitlab-docs` project for the `$DOCS_BRANCH` (defaults to `master`). + pipeline trigger in the `gitlab-org/gitlab-docs` project for the `$DOCS_BRANCH` (defaults to `main`). 1. The preview URL is shown both at the job output and in the merge request widget. You also get the link to the remote pipeline. 1. In the `gitlab-org/gitlab-docs` project, the pipeline is created and it @@ -477,7 +479,7 @@ The following GitLab features are used among others: - [Multi project pipelines](../../ci/multi_project_pipelines.md) - [Review Apps](../../ci/review_apps/index.md) - [Artifacts](../../ci/yaml/README.md#artifacts) -- [Specific runner](../../ci/runners/README.md#prevent-a-specific-runner-from-being-enabled-for-other-projects) +- [Specific runner](../../ci/runners/runners_scope.md#prevent-a-specific-runner-from-being-enabled-for-other-projects) - [Pipelines for merge requests](../../ci/merge_request_pipelines/index.md) ## Testing @@ -491,7 +493,7 @@ GitLab uses [Danger](https://github.com/danger/danger) for some elements in code review. For docs changes in merge requests, whenever a change to files under `/doc` is made, Danger Bot leaves a comment with further instructions about the documentation process. This is configured in the `Dangerfile` in the GitLab repository under -[/danger/documentation/](https://gitlab.com/gitlab-org/gitlab/tree/master/danger/documentation). +[/danger/documentation/](https://gitlab.com/gitlab-org/gitlab/-/tree/master/danger/documentation). ## Automatic screenshot generator diff --git a/doc/development/documentation/restful_api_styleguide.md b/doc/development/documentation/restful_api_styleguide.md index e05f6760ff1..b3d3e2641b7 100644 --- a/doc/development/documentation/restful_api_styleguide.md +++ b/doc/development/documentation/restful_api_styleguide.md @@ -33,7 +33,8 @@ In the Markdown doc for a resource (AKA endpoint): ## API topic template -The following can be used as a template to get started: +Use the following template to help you get started. Be sure to list any +required attributes first in the table. ````markdown ## Descriptive title @@ -50,8 +51,10 @@ Supported attributes: | Attribute | Type | Required | Description | |:------------|:---------|:---------|:----------------------| -| `attribute` | datatype | yes/no | Detailed description. | -| `attribute` | datatype | yes/no | Detailed description. | +| `attribute` | datatype | **{check-circle}** Yes | Detailed description. | +| `attribute` | datatype | **{dotted-circle}** No | Detailed description. | +| `attribute` | datatype | **{dotted-circle}** No | Detailed description. | +| `attribute` | datatype | **{dotted-circle}** No | Detailed description. | Example request: @@ -147,7 +150,8 @@ 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" +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: @@ -169,7 +173,8 @@ Instead of using JSON or URL-encoding data, you can use `multipart/form-data` wh properly handles data encoding: ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "title=ssh-key" --form "key=ssh-rsa AAAAB3NzaC1yc2EA..." "https://gitlab.example.com/api/v4/users/25/keys" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "title=ssh-key" \ + --form "key=ssh-rsa AAAAB3NzaC1yc2EA..." "https://gitlab.example.com/api/v4/users/25/keys" ``` The above example is run by and administrator and will add an SSH public key @@ -195,5 +200,6 @@ exclude specific users when requesting a list of users for a project, you would do something like this: ```shell -curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --data "skip_users[]=<user_id>" --data "skip_users[]=<user_id>" "https://gitlab.example.com/api/v4/projects/<project_id>/users" +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --data "skip_users[]=<user_id>" \ + --data "skip_users[]=<user_id>" "https://gitlab.example.com/api/v4/projects/<project_id>/users" ``` diff --git a/doc/development/documentation/site_architecture/deployment_process.md b/doc/development/documentation/site_architecture/deployment_process.md index d92f58e5501..1b764ada87b 100644 --- a/doc/development/documentation/site_architecture/deployment_process.md +++ b/doc/development/documentation/site_architecture/deployment_process.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Documentation deployment process -The [`dockerfiles` directory](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/dockerfiles/) +The [`dockerfiles` directory](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/dockerfiles/) contains all needed Dockerfiles to build and deploy <https://docs.gitlab.com>. It is heavily inspired by Docker's [Dockerfile](https://github.com/docker/docker.github.io/blob/06ed03db13895bfe867761b6fc2ad40acf6026dd/Dockerfile). @@ -15,10 +15,10 @@ The following Dockerfiles are used. | Dockerfile | Docker image | Description | | ---------- | ------------ | ----------- | -| [`Dockerfile.bootstrap`](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/dockerfiles/Dockerfile.bootstrap) | `gitlab-docs:bootstrap` | Contains all the dependencies that are needed to build the website. If the gems are updated and `Gemfile{,.lock}` changes, the image must be rebuilt. | -| [`Dockerfile.builder.onbuild`](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/dockerfiles/Dockerfile.builder.onbuild) | `gitlab-docs:builder-onbuild` | Base image to build the docs website. It uses `ONBUILD` to perform all steps and depends on `gitlab-docs:bootstrap`. | -| [`Dockerfile.nginx.onbuild`](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/dockerfiles/Dockerfile.nginx.onbuild) | `gitlab-docs:nginx-onbuild` | Base image to use for building documentation archives. It uses `ONBUILD` to perform all required steps to copy the archive, and relies upon its parent `Dockerfile.builder.onbuild` that is invoked when building single documentation archives (see the `Dockerfile` of each branch. | -| [`Dockerfile.archives`](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/dockerfiles/Dockerfile.archives) | `gitlab-docs:archives` | Contains all the versions of the website in one archive. It copies all generated HTML files from every version in one location. | +| [`Dockerfile.bootstrap`](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/dockerfiles/Dockerfile.bootstrap) | `gitlab-docs:bootstrap` | Contains all the dependencies that are needed to build the website. If the gems are updated and `Gemfile{,.lock}` changes, the image must be rebuilt. | +| [`Dockerfile.builder.onbuild`](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/dockerfiles/Dockerfile.builder.onbuild) | `gitlab-docs:builder-onbuild` | Base image to build the docs website. It uses `ONBUILD` to perform all steps and depends on `gitlab-docs:bootstrap`. | +| [`Dockerfile.nginx.onbuild`](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/dockerfiles/Dockerfile.nginx.onbuild) | `gitlab-docs:nginx-onbuild` | Base image to use for building documentation archives. It uses `ONBUILD` to perform all required steps to copy the archive, and relies upon its parent `Dockerfile.builder.onbuild` that is invoked when building single documentation archives (see the `Dockerfile` of each branch. | +| [`Dockerfile.archives`](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/dockerfiles/Dockerfile.archives) | `gitlab-docs:archives` | Contains all the versions of the website in one archive. It copies all generated HTML files from every version in one location. | ## How to build the images @@ -36,7 +36,7 @@ and tag all tooling images locally: ``` For each image, there's a manual job under the `images` stage in -[`.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/.gitlab-ci.yml) which can be invoked at any time. +[`.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/.gitlab-ci.yml) which can be invoked at any time. ## Update an old Docker image with new upstream docs content @@ -55,10 +55,10 @@ The website keeps changing and being improved. In order to consolidate those changes to the stable branches, we'd need to pick certain changes from time to time. -If this is not possible or there are many changes, merge master into them: +If this is not possible or there are many changes, merge main into them: ```shell git branch 12.0 -git fetch origin master -git merge origin/master +git fetch origin main +git merge origin/main ``` diff --git a/doc/development/documentation/site_architecture/global_nav.md b/doc/development/documentation/site_architecture/global_nav.md index 7175a9f1a5c..aeaf12e23d1 100644 --- a/doc/development/documentation/site_architecture/global_nav.md +++ b/doc/development/documentation/site_architecture/global_nav.md @@ -23,7 +23,7 @@ Global navigation (the left-most pane in our three pane documentation) provides: ## Adding new items To add a topic to the global nav, edit -[`navigation.yaml`](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/content/_data/navigation.yaml) +[`navigation.yaml`](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/content/_data/navigation.yaml) and add your item. All new pages need a new navigation item. Without a navigation, the page becomes "orphaned". That @@ -109,7 +109,7 @@ the data among the nav in containers properly [styled](#css-classes). ### Data file The data file describes the structure of the navigation for the applicable project. -It is stored at <https://gitlab.com/gitlab-org/gitlab-docs/blob/master/content/_data/navigation.yaml> +It is stored at <https://gitlab.com/gitlab-org/gitlab-docs/blob/main/content/_data/navigation.yaml> and comprises of three main components: - Sections @@ -267,19 +267,19 @@ Examples of relative URLs: ### Layout file (logic) -The [layout](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/layouts/global_nav.html) +The [layout](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/layouts/global_nav.html) is fed by the [data file](#data-file), builds the global nav, and is rendered by the -[default](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/layouts/default.html) layout. +[default](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/layouts/default.html) layout. The global nav contains links from all [four upstream projects](index.md#architecture). The [global nav URL](#urls) has a different prefix depending on the documentation file you change. -| Repository | Link prefix | Final URL | -|----------------------------------------------------------------|-------------|-----------| -| <https://gitlab.com/gitlab-org/gitlab/tree/master/doc> | `ee/` |`https://docs.gitlab.com/ee/` | -| <https://gitlab.com/gitlab-org/omnibus-gitlab/tree/master/doc> | `omnibus/` |`https://docs.gitlab.com/omnibus/` | -| <https://gitlab.com/gitlab-org/gitlab-runner/tree/master/docs> | `runner/` |`https://docs.gitlab.com/runner/` | -| <https://gitlab.com/charts/gitlab/tree/master/doc> | `charts/` |`https://docs.gitlab.com/charts/` | +| Repository | Link prefix | Final URL | +|----------------------------------------------------------------|-------------|------------------------------------| +| <https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc> | `ee/` | `https://docs.gitlab.com/ee/` | +| <https://gitlab.com/gitlab-org/omnibus-gitlab/tree/master/doc> | `omnibus/` | `https://docs.gitlab.com/omnibus/` | +| <https://gitlab.com/gitlab-org/gitlab-runner/-/tree/main/docs> | `runner/` | `https://docs.gitlab.com/runner/` | +| <https://gitlab.com/charts/gitlab/tree/master/doc> | `charts/` | `https://docs.gitlab.com/charts/` | ### CSS classes diff --git a/doc/development/documentation/site_architecture/index.md b/doc/development/documentation/site_architecture/index.md index 35e9ab5157b..d410d77a1a0 100644 --- a/doc/development/documentation/site_architecture/index.md +++ b/doc/development/documentation/site_architecture/index.md @@ -49,9 +49,9 @@ GitLab docs content isn't kept in the `gitlab-docs` repository. All documentation files are hosted in the respective repository of each product, and all together are pulled to generate the docs website: -- [GitLab](https://gitlab.com/gitlab-org/gitlab/tree/master/doc) +- [GitLab](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc) - [Omnibus GitLab](https://gitlab.com/gitlab-org/omnibus-gitlab/tree/master/doc) -- [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner/tree/master/docs) +- [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner/-/tree/main/docs) - [GitLab Chart](https://gitlab.com/charts/gitlab/tree/master/doc) NOTE: @@ -114,7 +114,7 @@ located in the [Dockerfiles directory](https://gitlab.com/gitlab-org/gitlab-docs If you need to rebuild the Docker images immediately (must have maintainer level permissions): WARNING: -If you change the Dockerfile configuration and rebuild the images, you can break the master +If you change the Dockerfile configuration and rebuild the images, you can break the main pipeline in the main `gitlab` repository as well as in `gitlab-docs`. Create an image with a different name first and test it to ensure you do not break the pipelines. @@ -132,7 +132,7 @@ a different name first and test it to ensure you do not break the pipelines. ### Deploy the docs site Every four hours a scheduled pipeline builds and deploys the docs site. The pipeline -fetches the current docs from the main project's master branch, builds it with Nanoc +fetches the current docs from the main project's main branch, builds it with Nanoc and deploys it to <https://docs.gitlab.com>. If you need to build and deploy the site immediately (must have maintainer level permissions): @@ -196,11 +196,11 @@ The links pointing to the files should be similar to: ``` Nanoc then builds and renders those links correctly according with what's -defined in [`Rules`](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/Rules). +defined in [`Rules`](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/Rules). ## Linking to source files -A helper called [`edit_on_gitlab`](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/lib/helpers/edit_on_gitlab.rb) can be used +A helper called [`edit_on_gitlab`](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/lib/helpers/edit_on_gitlab.rb) can be used to link to a page's source file. We can link to both the simple editor and the web IDE. Here's how you can use it in a Nanoc layout: @@ -223,9 +223,9 @@ for its search function. This is how it works: every 24h and [stores](https://community.algolia.com/docsearch/inside-the-engine.html) the [DocSearch index](https://community.algolia.com/docsearch/how-do-we-build-an-index.html) on [Algolia's servers](https://community.algolia.com/docsearch/faq.html#where-is-my-data-hosted%3F). -1. On the docs side, we use a [DocSearch layout](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/layouts/docsearch.html) which +1. On the docs side, we use a [DocSearch layout](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/layouts/docsearch.html) which is present on pretty much every page except <https://docs.gitlab.com/search/>, - which uses its [own layout](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/layouts/instantsearch.html). In those layouts, + which uses its [own layout](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/layouts/instantsearch.html). In those layouts, 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. diff --git a/doc/development/documentation/site_architecture/release_process.md b/doc/development/documentation/site_architecture/release_process.md index 9329b93bb26..46c74335932 100644 --- a/doc/development/documentation/site_architecture/release_process.md +++ b/doc/development/documentation/site_architecture/release_process.md @@ -1,5 +1,6 @@ --- redirect_to: 'https://about.gitlab.com/handbook/engineering/ux/technical-writing/workflow/#monthly-documentation-releases' +remove_date: '2021-07-12' --- This file was moved to [another location](https://about.gitlab.com/handbook/engineering/ux/technical-writing/workflow/#monthly-documentation-releases). diff --git a/doc/development/documentation/structure.md b/doc/development/documentation/structure.md index 67bdbffa2a1..871fb26ce08 100644 --- a/doc/development/documentation/structure.md +++ b/doc/development/documentation/structure.md @@ -109,7 +109,7 @@ Create an issue when you want to track bugs or future work. Prerequisites: -- A minimum of Contributor access to a project in GitLab. +- You must have at least the Developer role for a project. To create an issue: diff --git a/doc/development/documentation/styleguide/index.md b/doc/development/documentation/styleguide/index.md index 0ac393a8509..225db273cb6 100644 --- a/doc/development/documentation/styleguide/index.md +++ b/doc/development/documentation/styleguide/index.md @@ -15,12 +15,13 @@ use the `#docs-processes` channel. In addition to this page, the following resources can help you craft and contribute to documentation: - [Doc contribution guidelines](../index.md) +- [A-Z word list](word_list.md) - [Doc style and consistency testing](../testing.md) - [UI text guidelines](https://design.gitlab.com/content/error-messages/) - [GitLab Handbook style guidelines](https://about.gitlab.com/handbook/communication/#writing-style-guidelines) - [Microsoft Style Guide](https://docs.microsoft.com/en-us/style-guide/welcome/) - [Google Developer Documentation Style Guide](https://developers.google.com/style) -- [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) +- [Recent updates to this guide](https://gitlab.com/dashboard/merge_requests?scope=all&state=merged&label_name[]=tw-style¬[label_name][]=docs%3A%3Afix) ## Documentation is the single source of truth (SSOT) @@ -305,13 +306,6 @@ GitLab documentation should be clear and easy to understand. - 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). -### Trademark - -Only use the GitLab name and trademarks in accordance with -[GitLab Brand Guidelines](https://about.gitlab.com/handbook/marketing/corporate-marketing/brand-activation/brand-guidelines/#trademark). - -Don't use the possessive form of the word GitLab (`GitLab's`). - ### Capitalization #### Headings @@ -371,7 +365,7 @@ Capitalize names of: - Methods or methodologies. For example, Continuous Integration, Continuous Deployment, Scrum, and Agile. -Follow the capitalization style listed at the [authoritative source](#links-to-external-documentation) +Follow the capitalization style listed at the authoritative source for the entity, which may use non-standard case styles. For example: GitLab and npm. @@ -499,39 +493,6 @@ You can use these fake tokens as examples: | Health check token | `Tu7BgjR9qeZTEyRzGG2P` | | Request profile token | `7VgpS4Ax5utVD2esNstz` | -### Usage list -<!-- vale off --> - -| Usage | Guidance | -|-----------------------|----------| -| above | Try to avoid extra words when referring to an example or table in a documentation page, but if required, use **previously** instead. | -| admin, admin area | Use **administration**, **administrator**, **administer**, or **Admin Area** instead. ([Vale](../testing.md#vale) rule: [`Admin.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/Admin.yml)) | -| allow, enable | Try to avoid, unless you are talking about security-related features. For example, instead of "This feature allows you to create a pipeline," use "Use this feature to create a pipeline." This phrasing is more active and is from the user perspective, rather than the person who implemented the feature. [View details](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/a/allow-allows). | -| and/or | Use **or** instead, or another sensible construction. | -| below | Try to avoid extra words when referring to an example or table in a documentation page, but if required, use **following** instead. | -| currently | Do not use when talking about the product or its features. The documentation describes the product as it is today. ([Vale](../testing.md#vale) rule: [`CurrentStatus.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/CurrentStatus.yml)) | -| easily | Do not use. If the user doesn't find the process to be these things, we lose their trust. | -| e.g. | Do not use Latin abbreviations. Use **for example**, **such as**, **for instance**, or **like** instead. ([Vale](../testing.md#vale) rule: [`LatinTerms.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/LatinTerms.yml)) | -| future tense | When possible, use present tense instead. For example, use `after you execute this command, GitLab displays the result` instead of `after you execute this command, GitLab will display the result`. ([Vale](../testing.md#vale) rule: [`FutureTense.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/FutureTense.yml)) | -| handy | Do not use. If the user doesn't find the process to be these things, we lose their trust. | -| high availability, HA | Do not use. Instead, direct readers to the GitLab [reference architectures](../../../administration/reference_architectures/index.md) for information about configuring GitLab for handling greater amounts of users. | -| I | Do not use first-person singular. Use **you**, **we**, or **us** instead. ([Vale](../testing.md#vale) rule: [`FirstPerson.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/FirstPerson.yml)) | -| i.e. | Do not use Latin abbreviations. Use **that is** instead. ([Vale](../testing.md#vale) rule: [`LatinTerms.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/LatinTerms.yml)) | -| jargon | Do not use. Define the term or [link to a definition](#links-to-external-documentation). | -| may, might | **Might** means something has the probability of occurring. **May** gives permission to do something. Consider **can** instead of **may**. | -| me, myself, mine | Do not use first-person singular. Use **you**, **we**, or **us** instead. ([Vale](../testing.md#vale) rule: [`FirstPerson.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/FirstPerson.yml)) | -| please | Do not use. For details, see the [Microsoft style guide](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/p/please). | -| profanity | Do not use. Doing so may negatively affect other users and contributors, which is contrary to the GitLab value of [Diversity, Inclusion, and Belonging](https://about.gitlab.com/handbook/values/#diversity-inclusion). | -| scalability | Do not use when talking about increasing GitLab performance for additional users. The words scale or scaling are sometimes acceptable, but references to increasing GitLab performance for additional users should direct readers to the GitLab [reference architectures](../../../administration/reference_architectures/index.md) page. | -| simply | Do not use. If the user doesn't find the process to be these things, we lose their trust. | -| slashes | Instead of **and/or**, use **or** or another sensible construction. This rule also applies to other slashes, like **follow/unfollow**. Some exceptions (like **CI/CD**) are allowed. | -| subgroup | Use instead of `sub-group`. | -| that | Do not use. Example: `the file that you save` can be `the file you save`. | -| useful | Do not use. If the user doesn't find the process to be these things, we lose their trust. | -| utilize | Do not use. Use **use** instead. It's more succinct and easier for non-native English speakers to understand. | -| via | Do not use Latin abbreviations. Use **with**, **through**, or **by using** instead. ([Vale](../testing.md#vale) rule: [`LatinTerms.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/LatinTerms.yml)) | - -<!-- vale on --> ### Contractions Contractions are encouraged, and can create a friendly and informal tone, @@ -540,7 +501,7 @@ especially in tutorials, instructional documentation, and Some contractions, however, should be avoided: -- Do not use [the word GitLab in a contraction](#trademark). +- Do not use the word "GitLab" in a contraction. - Do not use contractions with a proper noun and a verb. For example: @@ -1108,36 +1069,42 @@ 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. +When documenting navigation through the user interface, use these terms and styles. ### What to call the menus Use these 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. +- **Top bar**: This is the top bar that spans the width of the user interface. + It includes the menu, 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. -### How to document the left sidebar +### How to document the menus -To be consistent, use this format when you refer to the left sidebar. +To be consistent, use this format when you write about UI navigation. -- Go to your project and select **Settings > CI/CD**. -- Go to your group and select **Settings > CI/CD**. -- Go to the Admin Area (**{admin}**) and select **Overview > Projects**. +1. On the top bar, select **Menu > Project** and find your project. +1. On the left sidebar, select **Settings > CI/CD**. +1. Expand **General pipelines**. -For expandable menus, use this format: +Another example: -1. Go to your group and select **Settings > CI/CD**. +1. On the top bar, select **Menu > Group** and find your group. +1. On the left sidebar, select **Settings > CI/CD**. 1. Expand **General pipelines**. +An Admin Area example: + +`1. On the top bar, select **Menu >** **{admin}** **Admin**.` + +This text generates this HTML: + +1. On the top bar, select **Menu >** **{admin}** **Admin**. + ## Images Images, including screenshots, can help a reader better understand a concept. @@ -1309,7 +1276,7 @@ hidden on the documentation site, but is displayed by `/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]`. + For example, `.gitlab-ci.yml`, `git add .`, `CODEOWNERS`, or `only: [main]`. 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 @@ -1416,10 +1383,10 @@ readability of the text. For example, this Markdown adds little to the accompanying text: ```markdown -1. Go to **{home}** **Project overview > Details**. +1. Go to **{home}** **Project information > Details**. ``` -1. Go to **{home}** **Project overview > Details**. +1. Go to **{home}** **Project information > Details**. However, these tables might help the reader connect the text to the user interface: diff --git a/doc/development/documentation/styleguide/word_list.md b/doc/development/documentation/styleguide/word_list.md new file mode 100644 index 00000000000..fd8766bbfb6 --- /dev/null +++ b/doc/development/documentation/styleguide/word_list.md @@ -0,0 +1,163 @@ +--- +stage: none +group: Style Guide +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +description: 'Writing styles, markup, formatting, and other standards for GitLab Documentation.' +--- + +# A-Z word list + +To help ensure consistency in the documentation, follow this guidance. + +<!-- vale off --> +<!-- markdownlint-disable --> + +## above + +Try to avoid extra words when referring to an example or table in a documentation page, but if required, use **previously** instead. + +## admin, admin area + +Use **administration**, **administrator**, **administer**, or **Admin Area** instead. ([Vale](../testing.md#vale) rule: [`Admin.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/Admin.yml)) + +## allow, enable + +Try to avoid, unless you are talking about security-related features. For example, instead of "This feature allows you to create a pipeline," use "Use this feature to create a pipeline." This phrasing is more active and is from the user perspective, rather than the person who implemented the feature. [View details](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/a/allow-allows). + +## and/or + +Instead of **and/or**, use or or rewrite the sentence to spell out both options. + +## below + +Try to avoid extra words when referring to an example or table in a documentation page, but if required, use **following** instead. + +## currently + +Do not use when talking about the product or its features. The documentation describes the product as it is today. ([Vale](../testing.md#vale) rule: [`CurrentStatus.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/CurrentStatus.yml)) + +## Developer + +When writing about the Developer role, use a capital "D." Do not use the phrase, "if you are a developer" +to mean someone who is assigned the Developer role. Instead, write it out. "If you are assigned the Developer role..." + +Do not use "Developer permissions." A user who is assigned the Developer role has a set of associated permissions. + +## easily + +Do not use. If the user doesn't find the process to be these things, we lose their trust. + +## e.g. + +Do not use Latin abbreviations. Use **for example**, **such as**, **for instance**, or **like** instead. ([Vale](../testing.md#vale) rule: [`LatinTerms.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/LatinTerms.yml)) + +## future tense + +When possible, use present tense instead. For example, use `after you execute this command, GitLab displays the result` instead of `after you execute this command, GitLab will display the result`. ([Vale](../testing.md#vale) rule: [`FutureTense.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/FutureTense.yml)) + +## GitLab + +Do not make possessive (GitLab's). This guidance follows [GitLab Brand Guidelines](https://about.gitlab.com/handbook/marketing/corporate-marketing/brand-activation/brand-guidelines/#trademark). + +## Guest + +When writing about the Guest role, use a capital "G." Do not use the phrase, "if you are a guest" +to mean someone who is assigned the Guest role. Instead, write it out. "If you are assigned the Guest role..." + +Do not use "Guest permissions." A user who is assigned the Guest role has a set of associated permissions. + +## handy + +Do not use. If the user doesn't find the process to be these things, we lose their trust. + +## high availability, HA + +Do not use. Instead, direct readers to the GitLab [reference architectures](../../../administration/reference_architectures/index.md) for information about configuring GitLab for handling greater amounts of users. + +## I + +Do not use first-person singular. Use **you**, **we**, or **us** instead. ([Vale](../testing.md#vale) rule: [`FirstPerson.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/FirstPerson.yml)) + +## i.e. + +Do not use Latin abbreviations. Use **that is** instead. ([Vale](../testing.md#vale) rule: [`LatinTerms.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/LatinTerms.yml)) + +## Maintainer + +When writing about the Maintainer role, use a capital "M." Do not use the phrase, "if you are a maintainer" +to mean someone who is assigned the Maintainer role. Instead, write it out. "If you are assigned the Maintainer role..." + +Do not use "Maintainer permissions." A user who is assigned the Maintainer role has a set of associated permissions. + +## may, might + +**Might** means something has the probability of occurring. **May** gives permission to do something. Consider **can** instead of **may**. + +## me, myself, mine + +Do not use first-person singular. Use **you**, **we**, or **us** instead. ([Vale](../testing.md#vale) rule: [`FirstPerson.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/FirstPerson.yml)) + +## Owner + +When writing about the Owner role, use a capital "M." Do not use the phrase, "if you are an owner" +to mean someone who is assigned the Owner role. Instead, write it out. "If you are assigned the Owner role..." + +Do not use "Owner permissions." A user who is assigned the Owner role has a set of associated permissions. + +## permissions + +Do not use roles and permissions interchangeably. Each user is assigned a role. Each role includes a set of permissions. + +## please + +Do not use. For details, see the [Microsoft style guide](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/p/please). + +## profanity + +Do not use. Doing so may negatively affect other users and contributors, which is contrary to the GitLab value of [Diversity, Inclusion, and Belonging](https://about.gitlab.com/handbook/values/#diversity-inclusion). + +## Reporter + +When writing about the Reporter role, use a capital "R." Do not use the phrase, "if you are a reporter" +to mean someone who is assigned the Reporter role. Instead, write it out. "If you are assigned the Reporter role..." + +Do not use "Reporter permissions." A user who is assigned the Reporter role has a set of associated permissions. + +## roles + +Do not use roles and permissions interchangeably. Each user is assigned a role. Each role includes a set of permissions. + +## scalability + +Do not use when talking about increasing GitLab performance for additional users. The words scale or scaling are sometimes acceptable, but references to increasing GitLab performance for additional users should direct readers to the GitLab [reference architectures](../../../administration/reference_architectures/index.md) page. + +## simply + +Do not use. If the user doesn't find the process to be these things, we lose their trust. + +## slashes + +Instead of **and/or**, use **or** or another sensible construction. This rule also applies to other slashes, like **follow/unfollow**. Some exceptions (like **CI/CD**) are allowed. + +## subgroup + +Use instead of `sub-group`. + +## that + +Do not use. Example: `the file that you save` can be `the file you save`. + +## useful + +Do not use. If the user doesn't find the process to be these things, we lose their trust. + +## utilize + +Do not use. Use **use** instead. It's more succinct and easier for non-native English speakers to understand. + +## via + +Do not use Latin abbreviations. Use **with**, **through**, or **by using** instead. ([Vale](../testing.md#vale) rule: [`LatinTerms.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/LatinTerms.yml)) + +<!-- vale on --> +<!-- markdownlint-enable --> diff --git a/doc/development/documentation/testing.md b/doc/development/documentation/testing.md index af95f3b9023..b634e2b93db 100644 --- a/doc/development/documentation/testing.md +++ b/doc/development/documentation/testing.md @@ -20,7 +20,7 @@ For the specifics of each test run in our CI/CD pipelines, see the configuration in the relevant projects: - <https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/ci/docs.gitlab-ci.yml> -- <https://gitlab.com/gitlab-org/gitlab-runner/-/blob/master/.gitlab/ci/docs.gitlab-ci.yml> +- <https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/.gitlab/ci/docs.gitlab-ci.yml> - <https://gitlab.com/gitlab-org/omnibus-gitlab/-/blob/master/gitlab-ci-config/gitlab-com.yml> - <https://gitlab.com/gitlab-org/charts/gitlab/-/blob/master/.gitlab-ci.yml> @@ -44,7 +44,7 @@ To run tests locally, it's important to: ### Lint checks -Lint checks are performed by the [`lint-doc.sh`](https://gitlab.com/gitlab-org/gitlab/blob/master/scripts/lint-doc.sh) +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. @@ -168,7 +168,7 @@ You can use markdownlint: [Vale](https://docs.errata.ai/vale/about/) 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 +[`.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 @@ -178,7 +178,7 @@ documentation directory of projects. You can find Vale configuration 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) +- [`gitlab-runner`](https://gitlab.com/gitlab-org/gitlab-runner/-/tree/main/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) @@ -222,7 +222,7 @@ build pipelines: ``` We recommend installing the version of `markdownlint-cli` - [used](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/master/.gitlab-ci.yml#L447) when building + [used (see `variables:` section)](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/.gitlab-ci.yml) when building the `image:docs-lint-markdown`. 1. Install [`vale`](https://github.com/errata-ai/vale/releases). For example, to install using @@ -240,7 +240,7 @@ It's important to use linter versions that are the same or newer than those run CI/CD. This provides access to new features and possible bug fixes. To match the versions of `markdownlint-cli` and `vale` used in the GitLab projects, refer to the -[versions used](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/master/.gitlab-ci.yml#L447) +[versions used (see `variables:` section)](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/.gitlab-ci.yml) when building the `image:docs-lint-markdown` Docker image containing these tools for CI/CD. | Tool | Version | Command | Additional information | @@ -273,7 +273,7 @@ To configure Vale in your editor, install one of the following as appropriate: - Select the **Use CLI** checkbox. - In the <!-- vale gitlab.Spelling = NO --> **Config** setting, enter an absolute - path to [`.vale.ini`](https://gitlab.com/gitlab-org/gitlab/blob/master/.vale.ini) + path to [`.vale.ini`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.vale.ini) in one of the cloned GitLab repositories on your computer. <!-- vale gitlab.Spelling = YES --> @@ -330,7 +330,18 @@ document: - 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). +Whenever possible, exclude only the problematic rule and lines. For more information, see [Vale's documentation](https://docs.errata.ai/vale/scoping#markup-based-configuration). + +### Disable markdownlint tests + +To disable all markdownlint rules, add a `<!-- markdownlint-disable -->` tag before the text, and a +`<!-- markdownlint-enable -->` tag after the text. + +To disable only a [specific rule](https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#rules), +add the rule number to the tag, for example `<!-- markdownlint-disable MD044 -->` +and `<!-- markdownlint-enable MD044 -->`. + +Whenever possible, exclude only the problematic lines. diff --git a/doc/development/documentation/workflow.md b/doc/development/documentation/workflow.md index 8e2028532e4..f035b4d0888 100644 --- a/doc/development/documentation/workflow.md +++ b/doc/development/documentation/workflow.md @@ -85,8 +85,8 @@ If you are a member of the GitLab Slack workspace, you can request help in `#doc ### Reviewing and merging -Anyone with Maintainer access to the relevant GitLab project can merge documentation changes. -Maintainers must make a good-faith effort to ensure that the content: +Anyone with the [Maintainer role](../../user/permissions.md) to the relevant GitLab project can +merge documentation changes. 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/index.md). @@ -115,7 +115,7 @@ The process involves the following: and link it from the merge request. The process is reflected in the **Documentation** -[merge request template](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/merge_request_templates/Documentation.md). +[merge request template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/merge_request_templates/Documentation.md). ## Other ways to help |