diff options
Diffstat (limited to 'doc/development/documentation')
| -rw-r--r-- | doc/development/documentation/index.md | 6 | ||||
| -rw-r--r-- | doc/development/documentation/review_apps.md | 4 | ||||
| -rw-r--r-- | doc/development/documentation/site_architecture/deployment_process.md | 2 | ||||
| -rw-r--r-- | doc/development/documentation/site_architecture/folder_structure.md | 98 | ||||
| -rw-r--r-- | doc/development/documentation/site_architecture/index.md | 15 | ||||
| -rw-r--r-- | doc/development/documentation/structure.md | 8 | ||||
| -rw-r--r-- | doc/development/documentation/styleguide/index.md | 132 | ||||
| -rw-r--r-- | doc/development/documentation/styleguide/word_list.md | 66 | ||||
| -rw-r--r-- | doc/development/documentation/testing.md | 40 | ||||
| -rw-r--r-- | doc/development/documentation/workflow.md | 4 |
10 files changed, 205 insertions, 170 deletions
diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index 776e5aefd00..5cf7bb74549 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -68,7 +68,7 @@ Adhere to the [Documentation Style Guide](styleguide/index.md). If a style stand ## Folder structure and files -See the [Structure](styleguide/index.md#structure) section of the [Documentation Style Guide](styleguide/index.md). +See the [Folder structure](site_architecture/folder_structure.md) page. ## Metadata @@ -290,9 +290,7 @@ For example, [GitLab.com's `/help`](https://gitlab.com/help). ## Docs site architecture -See the [Docs site architecture](site_architecture/index.md) page to learn -how we build and deploy the site at <https://docs.gitlab.com> and -to review all the assets and libraries in use. +For information on how we build and deploy <https://docs.gitlab.com>, see [Docs site architecture](site_architecture/index.md). ### Global navigation diff --git a/doc/development/documentation/review_apps.md b/doc/development/documentation/review_apps.md index 4b58778a20c..8cb9e6437b8 100644 --- a/doc/development/documentation/review_apps.md +++ b/doc/development/documentation/review_apps.md @@ -41,7 +41,7 @@ the GitLab team to run the job. 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.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/scripts/trigger-build.rb) 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 `main`). 1. The preview URL is shown both at the job output and in the merge request @@ -61,7 +61,7 @@ The following GitLab features are used among others: - [Review Apps](../../ci/review_apps/index.md) - [Artifacts](../../ci/yaml/index.md#artifacts) - [Specific runner](../../ci/runners/runners_scope.md#prevent-a-specific-runner-from-being-enabled-for-other-projects) -- [Pipelines for merge requests](../../ci/pipelines/merge_request_pipelines.md) +- [Merge request pipelines](../../ci/pipelines/merge_request_pipelines.md) ## Troubleshooting review apps diff --git a/doc/development/documentation/site_architecture/deployment_process.md b/doc/development/documentation/site_architecture/deployment_process.md index 25bc699c9d4..5203ca52922 100644 --- a/doc/development/documentation/site_architecture/deployment_process.md +++ b/doc/development/documentation/site_architecture/deployment_process.md @@ -82,7 +82,7 @@ for the stable branch of the image to rebuild. You might do this: ## Latest documentation -A Docker image (tagged `latest`) is built that contains: +We build a Docker image (tagged `latest`) that contains: - The latest online version of the documentation. - The documentation from the stable branches of upstream projects. diff --git a/doc/development/documentation/site_architecture/folder_structure.md b/doc/development/documentation/site_architecture/folder_structure.md new file mode 100644 index 00000000000..e960a6491c7 --- /dev/null +++ b/doc/development/documentation/site_architecture/folder_structure.md @@ -0,0 +1,98 @@ +--- +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/#assignments +--- + +# Folder structure for documentation + +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 | Contents | +|:----------------------|:------------------| +| `doc/user/` | Documentation for users. Anything that can be done in 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. Administrator settings in the GitLab user interface are under `doc/user/admin_area/`. | +| `doc/api/` | Documentation for the API. | +| `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/` | Instructions for installing GitLab. | +| `doc/update/` | 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 + +When working with directories and files: + +1. When you create a new directory, always start with an `index.md` file. + Don't use another filename and do not create `README.md` files. +1. Do not use special characters and spaces, or capital letters in file + 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](../styleguide/index.md#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 administrator-related + documentation describing what can be achieved by accessing the GitLab + administrator 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 administrator 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. You can also ask a technical writer at +any stage in the process. The technical writing team reviews 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.](../styleguide/index.md#link-instead-of-repeating-text) + +## References across documents + +- Give each folder an `index.md` page that introduces the topic, and both introduces + and links to the child pages, including to the index pages of + any next-level sub-paths. +- 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. diff --git a/doc/development/documentation/site_architecture/index.md b/doc/development/documentation/site_architecture/index.md index 60894430d15..e7a915eab09 100644 --- a/doc/development/documentation/site_architecture/index.md +++ b/doc/development/documentation/site_architecture/index.md @@ -52,19 +52,20 @@ product, and all together are pulled to generate the docs website: - [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner/-/tree/main/docs) - [GitLab Chart](https://gitlab.com/charts/gitlab/tree/master/doc) +Learn more about [the docs folder structure](folder_structure.md). + ## Assets To provide an optimized site structure, design, and a search-engine friendly website, along with a discoverable documentation, we use a few assets for the GitLab Documentation website. -### Libraries +### External libraries + +GitLab Docs is built with a combination of external: -- [Bootstrap 4.3.1 components](https://getbootstrap.com/docs/4.3/components/) -- [Bootstrap 4.3.1 JS](https://getbootstrap.com/docs/4.3/getting-started/javascript/) -- [jQuery](https://jquery.com/) 3.3.1 -- [Clipboard JS](https://clipboardjs.com/) -- [Font Awesome 4.7.0](https://fontawesome.com/v4.7.0/icons/) +- [JavaScript libraries](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/package.json). +- [Ruby libraries](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/Gemfile). ### SEO @@ -98,7 +99,7 @@ The pipeline in the `gitlab-docs` project: Once a week on Mondays, a scheduled pipeline runs and rebuilds the Docker images used in various pipeline jobs, like `docs-lint`. The Docker image configuration files are -located in the [Dockerfiles directory](https://gitlab.com/gitlab-org/gitlab-docs/-/tree/master/dockerfiles). +located in the [Dockerfiles directory](https://gitlab.com/gitlab-org/gitlab-docs/-/tree/main/dockerfiles). If you need to rebuild the Docker images immediately (must have maintainer level permissions): diff --git a/doc/development/documentation/structure.md b/doc/development/documentation/structure.md index 6ecffce01b4..21368098f39 100644 --- a/doc/development/documentation/structure.md +++ b/doc/development/documentation/structure.md @@ -5,10 +5,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w description: What to include in GitLab documentation pages. --- -# Documentation topic types +# Documentation topic types (CTRT) At GitLab, we have not traditionally used types for our content. However, we are starting to -move in this direction, and we now use four primary topic types: +move in this direction, and we now use four primary topic types (CTRT): - [Concept](#concept) - [Task](#task) @@ -154,7 +154,7 @@ If multiple causes or workarounds exist, consider putting them into a table form ## Other types of content There are other types of content in the GitLab documentation that don't -classify as one of the four primary [topic types](#documentation-topic-types). +classify as one of the four primary [topic types](#documentation-topic-types-ctrt). These include: - [Tutorials](#tutorials) @@ -174,7 +174,7 @@ In general, you might consider using a tutorial when: Tutorials are learning aids that complement our core documentation. They do not introduce new features. -Always use the primary [topic types](#documentation-topic-types) to document new features. +Always use the primary [topic types](#documentation-topic-types-ctrt) to document new features. Tutorials should be in this format: diff --git a/doc/development/documentation/styleguide/index.md b/doc/development/documentation/styleguide/index.md index e57ffb90028..3e9c0177d48 100644 --- a/doc/development/documentation/styleguide/index.md +++ b/doc/development/documentation/styleguide/index.md @@ -181,115 +181,6 @@ included in backticks. For example: - `git clone` is a command, so it must be lowercase, while Git is the product, so it must have a capital G. -## Structure - -We include concept and task topic types in the same larger topic. - -In general, we have one topic that's a landing page. -Below that topic in the left nav are individual topics. Each of these include a concept -and multiple related tasks, reference, and troubleshooting topics. - -### 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 | Contents | -|:----------------------|:------------------| -| `doc/user/` | Documentation for users. Anything that can be done in 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. Administrator settings in the GitLab user interface are under `doc/user/admin_area/`. | -| `doc/api/` | Documentation for the API. | -| `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/` | Instructions for installing GitLab. | -| `doc/update/` | 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 - -When working with directories and files: - -1. When you create a new directory, always start with an `index.md` file. - Don't use another filename and do not create `README.md` files. -1. Do not use special characters and spaces, or capital letters in file - 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 administrator-related - documentation describing what can be achieved by accessing the GitLab - administrator 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 administrator 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. You can also ask a technical writer at -any stage in the process. The technical writing team reviews 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-repeating-text) - -### References across documents - -- Give each folder an `index.md` page that introduces the topic, and both introduces - and links to the child pages, including to the index pages of - any next-level sub-paths. -- 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 in 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. @@ -320,10 +211,11 @@ 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 that name GitLab-specific - capabilities or tools. - -See the [word list](word_list.md) for details. +- Some features require title case, typically nouns that name GitLab-specific capabilities or tools. Features requiring + title case should be: + - Added as a proper name to markdownlint [configuration](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.markdownlint.yml), + so that it can be consistently applied across all documentation. + - Added to the [word list](word_list.md). If the term is not in the word list, ask a GitLab Technical Writer for advice. @@ -1151,7 +1043,8 @@ When you take screenshots: - **Review how the image renders on the page.** Preview the image locally or use the review app in the merge request. Make sure the image isn't blurry or overwhelming. - **Be consistent.** Coordinate screenshots with the other screenshots already on - a documentation page for a consistent reading experience. + a documentation page for a consistent reading experience. Ensure your navigation theme + is **Indigo** and the syntax highlighting theme is **Light**. These are the default preferences. ### Add callouts @@ -1745,11 +1638,12 @@ If the content in a topic is not ready, use the disclaimer in the topic. ### Removing versions after each major release -Whenever a major GitLab release occurs, we remove all version references -to now-unsupported versions of GitLab. Note that this includes the removal of -specific instructions for users of non-supported GitLab versions. For example, -if GitLab versions 11.x and later are supported, special -instructions for users of GitLab 10 should be removed. +When a major GitLab release occurs, we remove all references +to now-unsupported versions. This removal includes version-specific instructions. For example, +if GitLab version 12.1 and later are supported, +instructions for users of GitLab 11 should be removed. + +[View the list of supported versions](https://about.gitlab.com/support/statement-of-support.html#version-support). To view historical information about a feature, review GitLab [release posts](https://about.gitlab.com/releases/), or search for the issue or diff --git a/doc/development/documentation/styleguide/word_list.md b/doc/development/documentation/styleguide/word_list.md index dc3dcba0c95..2c435cdc69d 100644 --- a/doc/development/documentation/styleguide/word_list.md +++ b/doc/development/documentation/styleguide/word_list.md @@ -58,11 +58,7 @@ Capitalize these words when you refer to the UI. Otherwise use lowercase. ## administrator -Use **administrator** instead of **admin** when talking about a user's access level. -Use lowercase unless you are referring to the **Admin** access level you select in the UI. - -To view the administrator access level, in the GitLab UI, go to the Admin Area and select -**Users**. Then select **New user**. +Use **administrator access** instead of **admin** when talking about a user's access level.  @@ -71,7 +67,7 @@ An **administrator** is not a [role](#roles) or [permission](#permissions). Use: - To do this thing, you must be an administrator. -- To do this thing, you must have the administrator access level. +- To do this thing, you must have administrator access. Instead of: @@ -82,6 +78,17 @@ Instead of: Use title case **Admin Area** to refer to the area of the UI that you access when you select **Menu > Admin**. This area of the UI says **Admin Area** at the top of the page and on the menu. +## agent + +Use lowercase to refer to the [GitLab agent for Kubernetes](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent). +For example: + +- To connect your cluster to GitLab, use the GitLab agent for Kubernetes. +- Install the agent in your cluster. +- Select an agent from the list. + +Do not use title case **GitLab Agent** or **GitLab Agent for Kubernetes**. + ## allow, enable Try to avoid **allow** and **enable**, unless you are talking about security-related features. @@ -102,7 +109,7 @@ This phrasing is more active and is from the user perspective, rather than the p Use uppercase for **Alpha**. For example: **The XYZ feature is in Alpha.** or **This Alpha release is ready to test.** -You might also want to link to [this section](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha-beta-ga) +You might also want to link to [this section](../../../policy/alpha-beta-support.md#alpha-features) in the handbook when writing about Alpha features. ## and/or @@ -128,7 +135,7 @@ Try to avoid **below** when referring to an example or table in a documentation Use uppercase for **Beta**. For example: **The XYZ feature is in Beta.** or **This Beta release is ready to test.** -You might also want to link to [this section](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha-beta-ga) +You might also want to link to [this section](../../../policy/alpha-beta-support.md#beta-features) in the handbook when writing about Beta features. ## blacklist @@ -194,6 +201,10 @@ CI/CD is always uppercase. No need to spell it out on first use. Use **CI/CD minutes** instead of **CI minutes**, **pipeline minutes**, **pipeline minutes quota**, or **CI pipeline minutes**. This decision was made in [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/342813). +## CI/CD tunnel + +Use lowercase for **tunnel** in **CI/CD tunnel**. + ## click Do not use **click**. Instead, use **select** with buttons, links, menu items, and lists. @@ -312,6 +323,11 @@ Instead of: Use **expand** instead of **open** when you are talking about expanding or collapsing a section in the UI. +## FAQ + +We want users to find information quickly, and they rarely search for the term **FAQ**. +Information in FAQs belongs with other similar information, under an easily searchable topic title. + ## field Use **box** instead of **field** or **text box**. @@ -367,6 +383,11 @@ Use title case for **GitLab Runner**. This is the product you install. See also Use **GitLab self-managed** to refer to the product license for GitLab instances managed by customers themselves. +## guide + +We want to speak directly to users. On `docs.gitlab.com`, do not use **guide** as part of a page title. +For example, **Snowplow Guide**. Instead, speak about the feature itself, and how to use it. For example, **Use Snowplow to do xyz**. + ## Guest When writing about the Guest role: @@ -540,6 +561,8 @@ Do not use **navigate**. Use **go** instead. For example: - Go to this webpage. - Open a terminal and go to the `runner` directory. +([Vale](../testing.md#vale) rule: [`SubstitutionSuggestions.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/SubstitutionSuggestions.yml)) + ## need to, should Try to avoid **needs to**, because it's wordy. Avoid **should** when you can be more specific. If something is required, use **must**. @@ -658,10 +681,22 @@ Use **press** when talking about keyboard keys. For example: Do not use profanity. 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). +## provision + +Use the term **provision** when referring to provisioning cloud infrastructure. You provision the infrastructure, and then deploy applications to it. + +For example, you might write something like: + +- Provision an AWS EKS cluster and deploy your application to it. + ## push rules Use lowercase for **push rules**. +## register + +Use **register** instead of **sign up** when talking about creating an account. + ## Reporter When writing about the Reporter role: @@ -690,6 +725,9 @@ Roles are not the same as [**access levels**](#access-level). Use lowercase for **runners**. These are the agents that run CI/CD jobs. See also [GitLab Runner](#gitlab-runner) and [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/233529). +When referring to runners, if you have to specify that the runners are installed on a customer's GitLab instance, +use **self-managed** rather than **self-hosted**. + ## (s) Do not use **(s)** to make a word optionally plural. It can slow down comprehension. For example: @@ -735,6 +773,10 @@ Instead of: Use **select** with buttons, links, menu items, and lists. **Select** applies to more devices, while **click** is more specific to a mouse. +## self-managed + +Use **self-managed** to refer to a customer's installation of GitLab. Do not use **self-hosted**. + ## Service Desk Use title case for **Service Desk**. @@ -752,6 +794,10 @@ Use **sign in** instead of **sign on** or **log on** or **log in**. If the user You can use **single sign-on**. +## sign up + +Use **register** instead of **sign up** when talking about creating an account. + ## simply, simple Do not use **simply** or **simple**. If the user doesn't find the process to be simple, we lose their trust. ([Vale](../testing.md#vale) rule: [`Simplicity.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/Simplicity.yml)) @@ -883,10 +929,6 @@ Instead of: Do not use **utilize**. Use **use** instead. It's more succinct and easier for non-native English speakers to understand. ([Vale](../testing.md#vale) rule: [`SubstitutionSuggestions.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/SubstitutionSuggestions.yml)) -## Value Stream Analytics - -Use title case for **Value Stream Analytics**. - ## via Do not use Latin abbreviations. Use **with**, **through**, or **by using** instead. ([Vale](../testing.md#vale) rule: [`LatinTerms.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/LatinTerms.yml)) diff --git a/doc/development/documentation/testing.md b/doc/development/documentation/testing.md index 134183a0e75..905b44823c3 100644 --- a/doc/development/documentation/testing.md +++ b/doc/development/documentation/testing.md @@ -126,6 +126,24 @@ If you don't want to install all of the dependencies to test the links, you can: 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. +## Update linter configuration + +[Vale configuration](#vale) and [markdownlint configuration](#markdownlint) is under source control in each +project, so updates must be committed to each project individually. + +We consider the configuration in the `gitlab` project as the source of truth and that's where all updates should +first be made. + +On a regular basis, the changes made in `gitlab` project to the Vale and markdownlint configuration should be +synchronized to the other projects. In `omnibus-gitlab`, `gitlab-runner`, and `charts/gitlab`: + +1. Create a new branch. +1. Copy the configuration files from the `gitlab` project into this branch, overwriting + the project's old configuration. Make sure no project-specific changes from the `gitlab` + project are included. For example, [`RelativeLinks.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/RelativeLinks.yml) + is hard coded for specific projects. +1. Create a merge request and submit it to a technical writer for review and merge. + ## Local linters To help adhere to the [documentation style guidelines](styleguide/index.md), and improve the content @@ -181,7 +199,7 @@ You can find Vale configuration in the following projects: - [`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) +- [`gitlab-development-kit`](https://gitlab.com/gitlab-org/gitlab-development-kit/-/tree/main/doc/.vale/gitlab) This configuration is also used in build pipelines, where [error-level rules](#vale-result-types) are enforced. @@ -293,23 +311,7 @@ To configure Vale in your editor, install one of the following as appropriate: - Sublime Text [`SublimeLinter-contrib-vale` package](https://packagecontrol.io/packages/SublimeLinter-contrib-vale). - Visual Studio Code [`errata-ai.vale-server` extension](https://marketplace.visualstudio.com/items?itemName=errata-ai.vale-server). - You can configure the plugin to - [display only a subset of alerts](#show-subset-of-vale-alerts). - - In the extension's settings: - - <!-- vale gitlab.Spelling = NO --> - - - Select the **Use CLI** checkbox. - - In the **Config** setting, enter an absolute - path to [`.vale.ini`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.vale.ini) - in one of the cloned GitLab repositories on your computer. - - <!-- vale gitlab.Spelling = YES --> - - - In the **Path** setting, enter the absolute path to the Vale binary. In most - cases, `vale` should work. To find the location, run `which vale` in a terminal. - + You can configure the plugin to [display only a subset of alerts](#show-subset-of-vale-alerts). - Vim [ALE plugin](https://github.com/dense-analysis/ale). - Emacs [Flycheck extension](https://github.com/flycheck/flycheck). This requires some configuration: @@ -344,7 +346,7 @@ To configure Vale in your editor, install one of the following as appropriate: In this setup the `markdownlint` checker is set as a "next" checker from the defined `vale` checker. Enabling this custom Vale checker provides error linting from both Vale and markdownlint. -We don't use [Vale Server](https://errata-ai.github.io/vale/#using-vale-with-a-text-editor-or-another-third-party-application). +We don't use [Vale Server](https://docs.errata.ai/vale-server/install). ### Configure pre-push hooks diff --git a/doc/development/documentation/workflow.md b/doc/development/documentation/workflow.md index 49ad51874e3..a12af51e436 100644 --- a/doc/development/documentation/workflow.md +++ b/doc/development/documentation/workflow.md @@ -79,7 +79,7 @@ A member of the Technical Writing team adds these labels: ### Reviewing and merging -Anyone with the [Maintainer role](../../user/permissions.md) to the relevant GitLab project can +Anyone with the Maintainer role 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. @@ -157,7 +157,7 @@ Ensure the following if skipping an initial Technical Writer review: - Specific [user permissions](../../user/permissions.md) are documented. - New documents are linked from higher-level indexes, for discoverability. - The style guide is followed: - - For [directories and files](styleguide/index.md#work-with-directories-and-files). + - For [directories and files](site_architecture/folder_structure.md). - For [images](styleguide/index.md#images). Merge requests that change the location of documentation must always be reviewed by a Technical |