diff options
Diffstat (limited to 'doc/development/documentation')
| -rw-r--r-- | doc/development/documentation/feature_flags.md | 15 | ||||
| -rw-r--r-- | doc/development/documentation/index.md | 43 | ||||
| -rw-r--r-- | doc/development/documentation/restful_api_styleguide.md | 31 | ||||
| -rw-r--r-- | doc/development/documentation/site_architecture/deployment_process.md | 187 | ||||
| -rw-r--r-- | doc/development/documentation/site_architecture/global_nav.md | 11 | ||||
| -rw-r--r-- | doc/development/documentation/site_architecture/index.md | 33 | ||||
| -rw-r--r-- | doc/development/documentation/structure.md | 14 | ||||
| -rw-r--r-- | doc/development/documentation/styleguide/index.md | 67 | ||||
| -rw-r--r-- | doc/development/documentation/styleguide/word_list.md | 25 | ||||
| -rw-r--r-- | doc/development/documentation/workflow.md | 2 |
10 files changed, 324 insertions, 104 deletions
diff --git a/doc/development/documentation/feature_flags.md b/doc/development/documentation/feature_flags.md index c169af1958e..8fc6f2e2641 100644 --- a/doc/development/documentation/feature_flags.md +++ b/doc/development/documentation/feature_flags.md @@ -71,8 +71,14 @@ Possible version history entries are: > - [Enabled on GitLab.com](issue-link) in GitLab X.X. > - [Enabled on GitLab.com](issue-link) in GitLab X.X. Available to GitLab.com administrators only. > - [Enabled on self-managed](issue-link) in GitLab X.X. -> - [Feature flag <flag name> removed](issue-link) in GitLab X.X. -> - [Generally available](issue-link) in GitLab X.X. +> - [Generally available](issue-link) in GitLab X.Y. [Feature flag <flag name>](issue-link) removed. +``` + +You can combine entries if they happened in the same release: + +```markdown +> - Introduced in GitLab 14.2 [with a flag](../../administration/feature_flags.md) named `ci_include_rules`. Disabled by default. +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/337507) in GitLab 14.3. ``` ## Feature flag documentation examples @@ -84,7 +90,7 @@ The following examples show the progression of a feature flag. FLAG: On self-managed GitLab, by default this feature is not available. To make it available, -ask an administrator to [enable the featured flag](../administration/feature_flags.md) named `forti_token_cloud`. +ask an administrator to [enable the feature flag](../administration/feature_flags.md) named `forti_token_cloud`. The feature is not ready for production use. ``` @@ -105,6 +111,5 @@ And, when the feature is done and fully available to all users: > - Introduced in GitLab 13.7 [with a flag](../../administration/feature_flags.md) named `forti_token_cloud`. Disabled by default. > - [Enabled on self-managed](https://gitlab.com/issue/etc) GitLab 13.8. > - [Enabled on GitLab.com](https://gitlab.com/issue/etc) in GitLab 13.9. -> - [Feature flag removed](https://gitlab.com/issue/etc) in GitLab 14.0. -> - [Generally available](issue-link) in GitLab 14.0. +> - [Generally available](issue-link) in GitLab 14.0. [Feature flag <flag name>](issue-link) removed. ``` diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index 75538fe1fe7..776e5aefd00 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -170,22 +170,33 @@ it increases the work of the release managers. ## GitLab `/help` -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 `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. - -For example, let's say your merge request has a milestone set to 11.3, which -a release date of 2018-09-22. If it gets merged on 2018-09-15, it is -available online on 2018-09-15, but, as the feature freeze date has passed, if -the MR does not have a `~"Pick into 11.3"` label, the milestone has to be changed -to 11.4 and it ships with all GitLab packages only on 2018-10-22, -with GitLab 11.4. Meaning, it's available only with `/help` from GitLab -11.4 onward, but available on <https://docs.gitlab.com/> on the same day it was merged. +Every GitLab instance includes documentation at `/help` (`https://gitlab.example.com/help`) +that matches the version of the instance. For example, <https://gitlab.com/help>. + +The documentation available online at <https://docs.gitlab.com> is deployed every +four hours from the default branch of [GitLab, Omnibus, Runner, and Charts](#source-files-and-rendered-web-locations). +After a merge request that updates documentation is merged, it is available online +in 4 hours or less. + +However, it's only available at `/help` on self-managed instances in the next released +version. The date an update is merged can impact which self-managed release the update +is present in. + +For example: + +1. A merge request in `gitlab` updates documentation. It has a milestone of 14.4, + with an expected release date of 2021-10-22. +1. It is merged on 2021-10-19 and available online the same day at <https://docs.gitlab.com>. +1. GitLab 14.4 is released on 2021-10-22, based on the `gitlab` codebase from 2021-10-18 + (one day *before* the update was merged). +1. The change shows up in the 14.5 self-managed release, due to missing the release cutoff + for 14.4. + +The exact cutoff date for each release is flexible, and can be earlier or later +than expected due to holidays, weekends, or other events. In general, MRs merged +by the 17th should be present in the release on the 22nd, though it is not guaranteed. +If it is important that a documentation update is present in that month's release, +merge it as early as possible. ### Linking to `/help` diff --git a/doc/development/documentation/restful_api_styleguide.md b/doc/development/documentation/restful_api_styleguide.md index b3d3e2641b7..03980a42381 100644 --- a/doc/development/documentation/restful_api_styleguide.md +++ b/doc/development/documentation/restful_api_styleguide.md @@ -49,8 +49,8 @@ METHOD /endpoint Supported attributes: -| Attribute | Type | Required | Description | -|:------------|:---------|:---------|:----------------------| +| Attribute | Type | Required | Description | +| :---------- | :------- | :--------------------- | :-------------------- | | `attribute` | datatype | **{check-circle}** Yes | Detailed description. | | `attribute` | datatype | **{dotted-circle}** No | Detailed description. | | `attribute` | datatype | **{dotted-circle}** No | Detailed description. | @@ -80,16 +80,23 @@ to describe the GitLab release that introduced the API call. Use the following table headers to describe the methods. Attributes should always be in code blocks using backticks (`` ` ``). +Sort the attributes in the table: first, required, then alphabetically. + ```markdown -| Attribute | Type | Required | Description | -|:----------|:-----|:---------|:------------| +| Attribute | Type | Required | Description | +| :------------- | :------------ | :--------------------- | :--------------------------------------------------- | +| `user` | string | **{check-circle}** Yes | The GitLab username. | +| `assignee_ids` | integer array | **{dotted-circle}** No | The IDs of the users to assign the issue to. | +| `confidential` | boolean | **{dotted-circle}** No | Set an issue to be confidential. Default is `false`. | ``` Rendered example: -| Attribute | Type | Required | Description | -|:----------|:-------|:---------|:--------------------| -| `user` | string | yes | The GitLab username. | +| Attribute | Type | Required | Description | +| :------------- | :------------ | :--------------------- | :--------------------------------------------------- | +| `user` | string | **{check-circle}** Yes | The GitLab username. | +| `assignee_ids` | integer array | **{dotted-circle}** No | The IDs of the users to assign the issue to. | +| `confidential` | boolean | **{dotted-circle}** No | Set an issue to be confidential. Default is `false`. | ## cURL commands @@ -101,12 +108,12 @@ Rendered example: - Prefer to use examples using the personal access token and don't pass data of username and password. -| Methods | Description | -|:------------------------------------------- |:------------------------------------------------------| +| Methods | Description | +| :---------------------------------------------- | :----------------------------------------------------- | | `--header "PRIVATE-TOKEN: <your_access_token>"` | Use this method as is, whenever authentication needed. | -| `--request POST` | Use this method when creating new objects | -| `--request PUT` | Use this method when updating existing objects | -| `--request DELETE` | Use this method when removing existing objects | +| `--request POST` | Use this method when creating new objects | +| `--request PUT` | Use this method when updating existing objects | +| `--request DELETE` | Use this method when removing existing objects | ## cURL Examples diff --git a/doc/development/documentation/site_architecture/deployment_process.md b/doc/development/documentation/site_architecture/deployment_process.md index 1b764ada87b..c038ee96dbf 100644 --- a/doc/development/documentation/site_architecture/deployment_process.md +++ b/doc/development/documentation/site_architecture/deployment_process.md @@ -4,26 +4,158 @@ group: unassigned info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Documentation deployment process +# Documentation deployments + +The documentation [release process](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/doc/releases.md) +involves: + +- Merge requests, to make changes to the `main` and relevant stable branches. +- Pipelines, to build and deploy Docker images to the [`gitlab-docs` container registry](https://gitlab.com/gitlab-org/gitlab-docs/container_registry) + for the relevant stable branches. +- Docker images used to build and deploy all the online documentation, including stable versions and the latest documentation. + +Documentation deployments have dependencies on pipelines and Docker images as follows: + +- The latest documentation pipelines and images depend on the stable documentation pipelines and images. +- The Pages deployment pipelines depend on the latest documentation images (which, in turn, depend on the stable + pipelines and images.) + +For general information on using Docker with CI/CD pipelines, see [Docker integration](../../../ci/docker/index.md). + +## Stable branches + +Stable branches for documentation include the relevant stable branches of all the projects required to publish the entire +documentation suite. For example, the stable version of documentation for version `14.4` includes: + +- The [`14.4`](https://gitlab.com/gitlab-org/gitlab-docs/-/tree/14.4) branch of the `gitlab-docs` project. +- The [`14-4-stable-ee`](https://gitlab.com/gitlab-org/gitlab/-/tree/14-4-stable-ee) branch of the `gitlab` project. +- The [`14-4-stable`](https://gitlab.com/gitlab-org/gitlab-runner/-/tree/14-4-stable) branch of the `gitlab-runner` project. +- The [`14-4-stable`](https://gitlab.com/gitlab-org/omnibus-gitlab/-/tree/14-4-stable) branch of the `omnibus-gitlab` project. +- The [`5-4-stable`](https://gitlab.com/gitlab-org/charts/gitlab/-/tree/5-4-stable) branch of the `charts/gitlab` project. + `charts/gitlab` versions are [mapped](https://docs.gitlab.com/charts/installation/version_mappings.html) to GitLab + versions. + +The Technical Writing team +[creates the stable branch](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/doc/releases.md#create-stable-branch-and-docker-image-for-release) +for the `gitlab-docs` project, which makes use of the stable branches created by other teams. + +## Stable documentation + +When merge requests are merged that target stable branches of `gitlab-docs`, a pipeline builds +that stable documentation and deploys it to the registry. For example: + +- [14.4 merge request pipeline](https://gitlab.com/gitlab-org/gitlab-docs/-/pipelines/394459635). +- [14.3 merge request pipeline](https://gitlab.com/gitlab-org/gitlab-docs/-/pipelines/393774811). +- [14.2 merge request pipeline](https://gitlab.com/gitlab-org/gitlab-docs/-/pipelines/393774758). +- [13.12 merge request pipeline](https://gitlab.com/gitlab-org/gitlab-docs/-/pipelines/395365202). +- [12.10 merge request pipeline](https://gitlab.com/gitlab-org/gitlab-docs/-/pipelines/395365405). + +In particular, the [`image:docs-single` job](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/4c18963fe0a414ad62f55b9e18f922588b2dd155/.gitlab-ci.yml#L655) in each pipeline +takes what is built, and pushes it to the [container registry](https://gitlab.com/gitlab-org/gitlab-docs/container_registry/631635). + +```mermaid +graph TD + A["14.4 MR merged"] + B["14.3 MR merged"] + C["14.2 MR merged"] + D["13.12 MR merged"] + E["12.10 MR merged"] + F{{"Container registry on `gitlab-docs` project"}} + A--"`image:docs-single`<br>job runs and pushes<br>`gitlab-docs:14.4` image"-->F + B--"`image:docs-single`<br>job runs and pushes<br>`gitlab-docs:14.3` image"-->F + C--"`image:docs-single`<br>job runs and pushes<br>`gitlab-docs:14.2` image"-->F + D--"`image:docs-single`<br>job runs and pushes<br>`gitlab-docs:13.12` image"-->F + E--"`image:docs-single`<br>job runs and pushes<br>`gitlab-docs:12.10` image"-->F +``` -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). +### Rebuild stable documentation images + +To rebuild any of the stable documentation images, create a [new pipeline](https://gitlab.com/gitlab-org/gitlab-docs/-/pipelines/new) +for the stable branch of the image to rebuild. You might do this: + +- To include new documentation changes from an upstream stable branch into a stable version Docker image. For example, + rebuild the `14.4` Docker image to include changes subsequently merged in the `gitlab` project's + [`14-4-stable-ee`](https://gitlab.com/gitlab-org/gitlab/-/tree/14-4-stable-ee) branch. +- To incorporate changes made to the `gitlab-docs` project itself to a stable branch. For example: + - CSS style changes. + - Changes to the [version menu for a new release](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/doc/releases.md#update-dropdown-for-online-versions). + +## Latest documentation + +A Docker image (tagged `latest`) is built that contains: + +- The latest online version of the documentation. +- The documentation from the stable branches of upstream projects. + +The [`image:docs-latest` job](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/4c18963fe0a414ad62f55b9e18f922588b2dd155/.gitlab-ci.yml#L678): + +- Pulls the latest documentation from the default branches of the relevant upstream projects. +- Pulls the Docker images previously built by the `image:docs-single` jobs. + +For example, [a pipeline](https://gitlab.com/gitlab-org/gitlab-docs/-/pipelines/399233948) containing the +[`image:docs-latest` job](https://gitlab.com/gitlab-org/gitlab-docs/-/jobs/1733948330): + +```mermaid +graph TD + A["Latest `gitlab`, `gitlab-runner`<br>`omnibus-gitlab`, and `charts`"] + subgraph "Container registry on `gitlab-docs` project" + B["14.4 versioned docs<br>`gitlab-docs:14.4`"] + C["14.3 versioned docs<br>`gitlab-docs:14.3`"] + D["14.2 versioned docs<br>`gitlab-docs:14.2`"] + E["13.12 versioned docs<br>`gitlab-docs:13.12`"] + F["12.10 versioned docs<br>`gitlab-docs:12.10`"] + end + G[["Scheduled pipeline<br>`image:docs-latest` job<br>combines all these"]] + A--"Default branches<br>pulled down"-->G + B--"`gitlab-docs:14.4` image<br>pulled down"-->G + C--"`gitlab-docs:14.3` image<br>pulled down"-->G + D--"`gitlab-docs:14.2` image<br>pulled down"-->G + E--"`gitlab-docs:13.12` image<br>pulled down"-->G + F--"`gitlab-docs:12.10` image<br>pulled down"-->G + H{{"Container registry on gitlab-docs project"}} + G--"Latest `gitlab-docs:latest` image<br>pushed up"-->H +``` + +## Documentation Pages deployment + +[GitLab Docs](https://docs.gitlab.com) is a [Pages site](../../../user/project/pages/index.md) and documentation updates +for it must be deployed to become available. + +The [`pages`](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/4c18963fe0a414ad62f55b9e18f922588b2dd155/.gitlab-ci.yml#L491) +job runs the necessary commands to combine: + +- A very up-to-date build of the `gitlab-docs` site code. +- The latest docs from the default branches of the upstream projects. +- The documentation from `image:docs-latest`. + +For example, [a pipeline](https://gitlab.com/gitlab-org/gitlab-docs/-/pipelines/399233948) containing the +[`pages` job](https://gitlab.com/gitlab-org/gitlab-docs/-/jobs/1733948332). + +```mermaid +graph LR + A{{"Container registry on gitlab-docs project"}} + B[["Scheduled pipeline<br>`pages` and<br>`pages:deploy` job"]] + C([docs.gitlab.com]) + A--"`gitlab-docs:latest`<br>pulled"-->B + B--"Unpacked documentation uploaded"-->C +``` -The following Dockerfiles are used. +## Docker files -| Dockerfile | Docker image | Description | -| ---------- | ------------ | ----------- | -| [`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. | +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). + +| Dockerfile | Docker image | Description | +|:---------------------------------------------------------------------------------------------------------------------------|:------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [`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 +### How to build the images -Although build images are built automatically via GitLab CI/CD, you can build -and tag all tooling images locally: +Although build images are built automatically via GitLab CI/CD, you can build and tag all tooling images locally: 1. Make sure you have [Docker installed](https://docs.docker.com/install/). 1. Make sure you're in the `dockerfiles/` directory of the `gitlab-docs` repository. @@ -37,28 +169,3 @@ 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/main/.gitlab-ci.yml) which can be invoked at any time. - -## Update an old Docker image with new upstream docs content - -If there are any changes to any of the stable branches of the products that are -not included in the single Docker image, just rerun the pipeline (`https://gitlab.com/gitlab-org/gitlab-docs/pipelines/new`) -for the version in question. - -## Porting new website changes to old versions - -WARNING: -Porting changes to older branches can have unintended effects as we're constantly -changing the backend of the website. Use only when you know what you're doing -and make sure to test locally. - -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 main into them: - -```shell -git branch 12.0 -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 3845586ce60..6d2b93b9462 100644 --- a/doc/development/documentation/site_architecture/global_nav.md +++ b/doc/development/documentation/site_architecture/global_nav.md @@ -97,20 +97,13 @@ mechanics of what is required is [documented below](#data-file) but, in principl The global nav has five levels: -- **Section** +- Section - Category - Doc - Doc - Doc -The majority of the links available on the nav were added according to the UI. -The match is not perfect, as for some UI nav items the documentation doesn't -apply, and there are also other links to help the new users to discover the -documentation. The docs under **Administration** are ordered alphabetically -for clarity. - -To see the improvements planned, check the -[global nav epic](https://gitlab.com/groups/gitlab-org/-/epics/1599). +You can view this structure in [the navigation.yml file](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/content/_data/navigation.yaml). **Do not** [add items](#add-a-navigation-entry) 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 d1736e10000..60894430d15 100644 --- a/doc/development/documentation/site_architecture/index.md +++ b/doc/development/documentation/site_architecture/index.md @@ -124,12 +124,12 @@ Every four hours a scheduled pipeline builds and deploys the docs site. The pipe 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): +To build and deploy the site immediately (must have the Maintainer role): 1. In [`gitlab-docs`](https://gitlab.com/gitlab-org/gitlab-docs), go to **{rocket}** **CI/CD > Schedules**. 1. For the `Build docs.gitlab.com every 4 hours` scheduled pipeline, click the **play** (**{play}**) button. -Read more about the [deployment process](deployment_process.md). +Read more about [documentation deployments](deployment_process.md). ## Using YAML data files @@ -163,6 +163,35 @@ We can then loop over the `versions` array with something like: Note that the data file must have the `yaml` extension (not `yml`) and that we reference the array with a symbol (`:versions`). +## Archived documentation banner + +A banner is displayed on archived documentation pages with the text `This is archived documentation for +GitLab. Go to the latest.` when either: + +- The version of the documentation displayed is not the first version entry in `online` in + `content/_data/versions.yaml`. +- The documentation was built from the default branch (`main`). + +For example, if the `online` entries for `content/_data/versions.yaml` are: + +```yaml +online: + - "14.4" + - "14.3" + - "14.2" +``` + +In this case, the archived documentation banner isn't displayed: + +- For 14.4, the docs built from the `14.4` branch. The branch name is the first entry in `online`. +- For 14.5-pre, the docs built from the default project branch (`main`). + +The archived documentation banner is displayed: + +- For 14.3. +- For 14.2. +- For any other version. + ## Bumping versions of CSS and JavaScript Whenever the custom CSS and JavaScript files under `content/assets/` change, diff --git a/doc/development/documentation/structure.md b/doc/development/documentation/structure.md index 229dbb077fe..fac83af89f4 100644 --- a/doc/development/documentation/structure.md +++ b/doc/development/documentation/structure.md @@ -234,9 +234,21 @@ If you need to add more than one task, consider using subsections for each distinct task. ``` +### Related topics + +If inline links are not sufficient, you can create a topic called **Related topics** +and include a bulleted list of related topics. This topic should be above the Troubleshooting section. + +```markdown +# Related topics + +- [Configure your pipeline](link-to-topic) +- [Trigger a pipeline manually](link-to-topic) +``` + ### Topics and resources pages -This is a page with a list of links that point to important sections +This page has a list of links that point to important sections of documentation for a specific GitLab feature or tool. We do not encourage the use of these types of pages. diff --git a/doc/development/documentation/styleguide/index.md b/doc/development/documentation/styleguide/index.md index 72491ab3a33..1382ec263f2 100644 --- a/doc/development/documentation/styleguide/index.md +++ b/doc/development/documentation/styleguide/index.md @@ -317,8 +317,8 @@ create an issue or an MR to propose a change to the user interface text. #### Feature names -- *Feature names are typically lowercase*. -- *Some features are capitalized*, typically nouns naming GitLab-specific +- Feature names are typically lowercase. +- Some features are capitalized, typically nouns that name GitLab-specific capabilities or tools. See the [word list](word_list.md) for details. @@ -404,13 +404,13 @@ Some contractions, however, should be avoided: | Do | Don't | |------------------------------------------|-----------------------------------------| - | Do *not* install X with Y. | *Don't* install X with Y. | + | 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. | + | 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: @@ -701,7 +701,7 @@ that's best described by a matrix, tables are the best choice. To keep tables accessible and scannable, 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*. +**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: @@ -1026,18 +1026,13 @@ document to ensure it links to the most recent version of the file. When documenting how to navigate through the GitLab UI: - Always use location, then action. - - `From the **Visibility** list,` (location) `select **Public**.` (action) + - From the **Visibility** dropdown list (location), select **Public** (action). - Be brief and specific. For example: - - Avoid: `Select **Save** for the changes to take effect.` - - Use instead: `Select **Save**.` -- When selecting from high-level UI elements, use the word **on**. - - Avoid: `From the left sidebar...` or `In the left sidebar...` - - Use instead: `On the left sidebar...` -- If a step must include a reason, start the step with it. - - Avoid: `Select the link in the merge request to view the changes.` - - Use instead: `To view the changes, select the link in the merge request.` -- If a step is optional, start the step with the word `Optional` followed by a period. - - `1. Optional. Enter a name for the dog.` + - Do: Select **Save**. + - Do not: Select **Save** for the changes to take effect. +- If a step must include a reason, start the step with it. This helps the user scan more quickly. + - Do: To view the changes, in the merge request, select the link. + - Do not: Select the link in the merge request to view the changes. ### Names for menus @@ -1060,15 +1055,19 @@ Guidance for each individual UI element is in [the word list](word_list.md). To be consistent, use this format when you write navigation steps in a task topic. +```markdown 1. On the top bar, select **Menu > Projects** and find your project. 1. On the left sidebar, select **Settings > CI/CD**. 1. Expand **General pipelines**. +``` Another example: +```markdown 1. On the top bar, select **Menu > Groups** and find your group. 1. On the left sidebar, select **Settings > CI/CD**. 1. Expand **General pipelines**. +``` An Admin Area example: @@ -1082,6 +1081,42 @@ To select your avatar: 1. On the top bar, in the top right corner, select your avatar. ``` +### Optional steps + +If a step is optional, start the step with the word `Optional` followed by a period. + +For example: + +```markdown +1. Optional. Enter a description for the job. +``` + +### Documenting multiple fields at once + +If the UI text sufficiently explains the fields in a section, do not include a task step for every field. +Instead, summarize multiple fields in a single task step. + +Use the phrase **Complete the fields**. + +For example: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Repository**. +1. Expand **Push rules**. +1. Complete the fields. + +If you are documenting multiple fields and only one field needs explanation, do it in the same step: + +1. Expand **Push rules**. +1. Complete the fields. **Branch name** must be a regular expression. + +To describe multiple fields, use bullets: + +1. Expand **General pipelines**. +1. Complete the fields. + - **Branch name** must be a regular expression. + - **User** must be a user with at least the **Maintainer** role. + ## Images Images, including screenshots, can help a reader better understand a concept. diff --git a/doc/development/documentation/styleguide/word_list.md b/doc/development/documentation/styleguide/word_list.md index f1e6a147571..595dab09bf5 100644 --- a/doc/development/documentation/styleguide/word_list.md +++ b/doc/development/documentation/styleguide/word_list.md @@ -259,6 +259,16 @@ Use **box** instead of **field** or **text box**. - Do: In the **Variable name** box, enter `my text`. - Do not: In the **Variable name** field, enter `my text`. +However, you can make an exception when you are writing a task and you need to refer to all +of the fields at once. For example: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > CI/CD**. +1. Expand **General pipelines**. +1. Complete the fields. + +Learn more about [documenting multiple fields at once](index.md#documenting-multiple-fields-at-once). + ## foo Do not use **foo** in product documentation. You can use it in our API and contributor documentation, but try to use a clearer and more meaningful example instead. @@ -454,6 +464,13 @@ Do not use **note that** because it's wordy. - Do: You can change the settings. - Do not: Note that you can change the settings. +## on + +When documenting how to select high-level UI elements, use the word **on**. + +- Do: `On the left sidebar...` +- Do not: `From the left sidebar...` or `In the left sidebar...` + ## once The word **once** means **one time**. Don't use it to mean **after** or **when**. @@ -524,8 +541,8 @@ Use lowercase for **runners**. These are the agents that run CI/CD jobs. See als Do not use **(s)** to make a word optionally plural. It can slow down comprehension. For example: -Do: Select the jobs you want. -Do not: Select the job(s) you want. +- Do: Select the jobs you want. +- Do not: Select the job(s) you want. If you can select multiples of something, then write the word as plural. @@ -555,6 +572,10 @@ or collapsing a section, don't include the word **section**. Use **select** with buttons, links, menu items, and lists. **Select** applies to more devices, while **click** is more specific to a mouse. +## Service Desk + +Use title case for **Service Desk**. + ## setup, set up Use **setup** as a noun, and **set up** as a verb. For example: diff --git a/doc/development/documentation/workflow.md b/doc/development/documentation/workflow.md index 90c1137e5c5..782cd3411b1 100644 --- a/doc/development/documentation/workflow.md +++ b/doc/development/documentation/workflow.md @@ -39,7 +39,7 @@ The following are also added by members of the Technical Writing team: - The `~Technical Writing` [team label](../contributing/issue_workflow.md#team-labels). Documentation changes that are not associated with the release of a new or updated feature -do not take the `~feature` label, but still need the `~documentation` label. +do not take the `~"type::feature"` label, but still need the `~documentation` label. They may include: |