diff options
Diffstat (limited to 'doc/development/documentation')
| -rw-r--r-- | doc/development/documentation/graphql_styleguide.md | 2 | ||||
| -rw-r--r-- | doc/development/documentation/index.md | 20 | ||||
| -rw-r--r-- | doc/development/documentation/redirects.md | 60 | ||||
| -rw-r--r-- | doc/development/documentation/styleguide/index.md | 88 | ||||
| -rw-r--r-- | doc/development/documentation/styleguide/word_list.md | 37 | ||||
| -rw-r--r-- | doc/development/documentation/testing.md | 37 |
6 files changed, 134 insertions, 110 deletions
diff --git a/doc/development/documentation/graphql_styleguide.md b/doc/development/documentation/graphql_styleguide.md index 5acc8bda6a6..ad19a40a3f5 100644 --- a/doc/development/documentation/graphql_styleguide.md +++ b/doc/development/documentation/graphql_styleguide.md @@ -6,7 +6,7 @@ info: "See the Technical Writers assigned to Development Guidelines: https://abo description: "Writing styles, markup, formatting, and other standards for GraphQL API's GitLab Documentation." --- -# GraphQL API +# Creating a GraphQL example page GraphQL APIs are different from [RESTful APIs](restful_api_styleguide.md). Reference information is generated in our [GraphQL reference](../../api/graphql/reference/index.md). diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index 5cf7bb74549..66d6beb821f 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -7,7 +7,7 @@ description: Learn how to contribute to GitLab Documentation. # GitLab Documentation guidelines -The GitLab documentation is [intended as the single source of truth (SSOT)](https://about.gitlab.com/handbook/documentation/) for information about how to configure, use, and troubleshoot GitLab. The documentation contains use cases and usage instructions for every GitLab feature, organized by product area and subject. This includes topics and workflows that span multiple GitLab features, and the use of GitLab with other applications. +The GitLab documentation is [intended as the single source of truth (SSOT)](https://about.gitlab.com/handbook/documentation/) for information about how to configure, use, and troubleshoot GitLab. The documentation contains use cases and usage instructions for every GitLab feature, organized by product area and subject. This includes topics and workflows that span multiple GitLab features and the use of GitLab with other applications. In addition to this page, the following resources can help you craft and contribute to documentation: @@ -55,9 +55,9 @@ docs-only merge requests using the following guide: [Contributions to GitLab docs](workflow.md) are welcome from the entire GitLab community. -To ensure that GitLab docs are current, there are special processes and responsibilities for all [feature changes](workflow.md), that is development work that impacts the appearance, usage, or administration of a feature. +To ensure that the GitLab docs are current, there are special processes and responsibilities for all [feature changes](workflow.md), that is development work that impacts the appearance, usage, or administration of a feature. -However, anyone can contribute [documentation improvements](workflow.md) that are not associated with a feature change. For example, adding a new doc on how to accomplish a use case that's already possible with GitLab or with third-party tools and GitLab. +However, anyone can contribute [documentation improvements](workflow.md) that are not associated with a feature change. For example, adding a new document on how to accomplish a use case that's already possible with GitLab or with third-party tools and GitLab. ## Markdown and styles @@ -87,8 +87,8 @@ belongs to, as well as an information block as described below: - `group`: The [Group](https://about.gitlab.com/company/team/structure/#product-groups) to which the majority of the page's content belongs. - `info`: The following line, which provides direction to contributors regarding - how to contact the Technical Writer associated with the page's Stage and - Group: + how to contact the Technical Writer associated with the page's stage and + group: ```plaintext To determine the technical writer assigned to the Stage/Group @@ -116,7 +116,7 @@ The following metadata should be added when a page is moved to another location: location to which visitors should be redirected for a moved page. [Learn more](redirects.md). - `disqus_identifier`: Identifier for Disqus commenting system. Used to keep - comments with a page that's been moved to a new URL. + comments with a page that has been moved to a new URL. [Learn more](redirects.md#redirections-for-pages-with-disqus-comments). ### Comments metadata @@ -192,8 +192,8 @@ For example: 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 +The exact cutoff date for each release is flexible, and can be sooner 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. @@ -209,7 +209,7 @@ with the following conventions: - It's relative to the `doc/` directory in the GitLab repository. - It omits the `.md` extension. -- It doesn't end with a slash (`/`). +- It doesn't end with a forward slash (`/`). The help text follows the [Pajamas guidelines](https://design.gitlab.com/usability/helping-users/#formatting-help-content). @@ -316,7 +316,7 @@ process. This is configured in the `Dangerfile` in the GitLab repository under ## Automatic screenshot generator -You can now set up an automatic screenshot generator to take and compress screenshots, with the +You can now set up an automatic screenshot generator to take and compress screenshots with the help of a configuration file known as **screenshot generator**. ### Use the tool diff --git a/doc/development/documentation/redirects.md b/doc/development/documentation/redirects.md index 8f13048f663..4c748924c67 100644 --- a/doc/development/documentation/redirects.md +++ b/doc/development/documentation/redirects.md @@ -27,7 +27,7 @@ Add a redirect to ensure: - Users see the new page and can update or delete their bookmark. - External sites can update their links, especially sites that have automation that - check for redirecting links. + checks for redirected links. - The documentation site global navigation does not link to a missing page. The links in the global navigation are already tested in the `gitlab-docs` project. @@ -38,26 +38,28 @@ Technical Writers can help with any questions and can review your change. There are two types of redirects: -- Redirect added into the documentation files themselves, for users who +- [Redirect added into the documentation files themselves](#add-a-redirect), for users who view the docs in `/help` on self-managed instances. For example, - [`/help` on GitLab.com](https://gitlab.com/help). -- [GitLab Pages redirects](../../user/project/pages/redirects.md), - for users who view the docs on [`docs.gitlab.com`](https://docs.gitlab.com). + [`/help` on GitLab.com](https://gitlab.com/help). These must be added in the same + MR that renames or moves a doc. Redirects to internal pages expire after three months + and redirects to external pages (starting with `https:`) expire after a year. +- [GitLab Pages redirects](../../user/project/pages/redirects.md), which are added + automatically after redirect files expire. They must not be manually added by + contributors and expire after nine months. Redirects pointing to external sites + are not added to the GitLab Pages redirects. - 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 and [clean up the redirects](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/doc/raketasks.md#clean-up-redirects). - If you're a contributor, you may add a new redirect, but you don't need to delete - the old ones. This process is automatic and handled by the Technical - Writing team. +Expired redirect files are removed from the documentation projects by the +[`clean_redirects` Rake task](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/doc/raketasks.md#clean-up-redirects), +as part of the Technical Writing team's [monthly tasks](https://gitlab.com/gitlab-org/technical-writing/-/blob/main/.gitlab/issue_templates/tw-monthly-tasks.md). + +## Add a redirect NOTE: -If the old page you're renaming doesn't exist in a stable branch, skip the -following steps and ask a Technical Writer to add the redirect in -[`redirects.yaml`](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/content/_data/redirects.yaml). -For example, if you add a new page on the 3rd of the month and then rename it before it gets -added in the stable branch on the 18th, the old page will never be part of the internal `/help`. -In that case, you can jump straight to the -[Pages redirect](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/doc/maintenance.md#pages-redirects). +If the renamed page is new, you can sometimes skip the following steps and ask a +Technical Writer to manually add the redirect to [`redirects.yaml`](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/content/_data/redirects.yaml). +For example, if you add a new page and then rename it before it's added to a release +on the 18th. The old page is not in any version's `/help` section, so a technical writer +can jump straight to the [Pages redirect](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/doc/maintenance.md#pages-redirects). To add a redirect: @@ -87,20 +89,13 @@ To add a redirect: bundle exec rake "gitlab:docs:redirect[doc/user/search/old_file.md, https://example.com]" ``` - Alternatively, you can omit the arguments and be asked to enter their values: - - ```shell - bundle exec rake gitlab:docs:redirect - ``` - - If you don't want to use the Rake task, you can use the following template. + - Alternatively, you can omit the arguments and be prompted to enter the values: - Replace the value of `redirect_to` with the new file path and `YYYY-MM-DD` - with the date the file should be removed. + ```shell + bundle exec rake gitlab:docs:redirect + ``` - Redirect files that link to docs in internal documentation projects - are removed after three months. Redirect files that link to external sites are - removed after one year: + If you don't want to use the Rake task, you can use the following template: ```markdown --- @@ -111,9 +106,14 @@ To add a redirect: This document was moved to [another location](../path/to/file/index.md). <!-- This redirect file can be deleted after <YYYY-MM-DD>. --> - <!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> + <!-- Redirects that point to other docs in the same project expire in three months. --> + <!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> + <!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> ``` + - Replace both instances of `../newpath/to/file/index.md` with the new file path. + - Replace `YYYY-MM-DD` with the expiry date, as explained in the template. + 1. If the documentation page being moved has any Disqus comments, follow the steps described in [Redirections for pages with Disqus comments](#redirections-for-pages-with-disqus-comments). 1. Open a merge request with your changes. If a documentation page diff --git a/doc/development/documentation/styleguide/index.md b/doc/development/documentation/styleguide/index.md index 3e9c0177d48..91e9d0c703d 100644 --- a/doc/development/documentation/styleguide/index.md +++ b/doc/development/documentation/styleguide/index.md @@ -655,52 +655,39 @@ This is overridden by the [documentation-specific punctuation rules](#punctuatio ## Headings -- Add only one H1 in each document, by adding `#` at the beginning of - it (when using Markdown). The `h1` becomes the document `<title>`. -- Start with an `h2` (`##`), and respect the order `h2` > `h3` > `h4` > `h5` > `h6`. - Never skip the hierarchy level, such as `h2` > `h4` -- Avoid putting numbers in headings. Numbers shift, hence documentation anchor - links shift too, which eventually leads to dead links. If you think it is - compelling to add numbers in headings, make sure to at least discuss it with - someone in the Merge Request. -- [Avoid using symbols and special characters](https://gitlab.com/gitlab-org/gitlab-docs/-/issues/84) - in headers. Whenever possible, they should be plain and short text. -- When possible, avoid including words that might change in the future. Changing +In the Markdown document: + +- Add one H1 (`#`) at the start of the page. The `h1` becomes the document `<title>`. +- After the H1, follow the order `h2` > `h3` > `h4` > `h5` > `h6`. +- Do not skip a level. For example: `h2` > `h4`. +- Leave one blank line before and after the heading. + +For the heading text, **do**: + +- Be clear and direct. Make every word count. +- Use active verbs for tasks. For example, `Configure GDK` instead of `Configuring GDK`. +- Talk about what the product does, realistically but from a positive perspective. Instead of + `Limitations`, move the content near other similar information. If you must, you can + use the title `Known issues`. +- Use articles and prepositions. +- Add the [product badge](#product-tier-badges) that corresponds to the license tier. +- Follow [capitalization](#capitalization) guidelines. + +For the heading text, **do not**: + +- Use generic words like `Overview` or `Use cases`. Instead, incorporate + the information under a concept heading. +- Use `How it works`. Incorporate this information under a concept, or use a + noun followed by `workflow`. For example, `Merge request workflow`. +- Use `Important Notes`. Incorporate this information closer to where it belongs. +- Use numbers to indicate steps. If the numbers change, the anchor links changes, + which eventually leads to dead links. If you think you must add numbers in headings, + at least discuss it with a writer in the merge request. +- Use words that might change in the future. Changing a heading changes its anchor URL, which affects other linked pages. -- When introducing a new document, be careful for the headings to be - grammatically and syntactically correct. Mention an [assigned technical writer (TW)](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments) - for review, based upon the [product category](https://about.gitlab.com/handbook/product/categories/). - This is to ensure that no document with wrong heading is going live without an - audit, thus preventing dead links and redirection issues when corrected. -- Use the context provided by parent section headings. That is, don't repeat the parent heading's text in each - subsection's heading. -- Use articles and prepositions in headings where it would make sense in regular text. -- Leave exactly one blank line before and after a heading. -- Do not use links in headings. -- Add the corresponding [product badge](#product-tier-badges) according to the tier the - feature belongs. -- Our documentation site search engine prioritizes words used in headings and - subheadings. Make your subheading titles clear, descriptive, and complete to help - users find the right example, as shown in the section on [heading titles](#heading-titles). -- See [Capitalization](#capitalization) for guidelines on capitalizing headings. - -### Heading titles - -Keep heading titles clear and direct. Make every word count. To accommodate -search engine optimization (SEO), use the imperative, where possible. - -| Do | Don't | -|:--------------------------------------|:------------------------------------------------------------| -| Configure GDK | Configuring GDK | -| GitLab Release and Maintenance Policy | This section covers the GitLab Release and Maintenance Policy | -| Backport to older releases | Backporting to older releases | -| GitLab Pages examples | Examples | - -For guidelines on capitalizing headings, see the section on [capitalization](#capitalization). - -NOTE: -If you change an existing title, be careful. In-page [anchor links](#anchor-links), -links in the GitLab application, and links from external sites can break. +- Repeat text from earlier headings. For example, instead of `Troubleshooting merge requests`, + use `Troubleshooting`. +- Use links. ### Anchor links @@ -1130,6 +1117,17 @@ copy of `https://gitlab.com/gitlab-org/gitlab`, run in a terminal: bin/pngquant compress doc/user/img ``` +### Animated images + +Sometimes an image with animation (such as an animated GIF) +can help the reader understand a complicated interaction with the user interface. + +However, you should use them sparingly and avoid them when you can. +Do not use them to replace written descriptions of processes or the product. + +If you include an animated image, follow the same size and naming conventions we use for images. If the animated image loops, add at least a three +second pause to the end of the loop. + ## Videos Adding GitLab YouTube video tutorials to the documentation is highly diff --git a/doc/development/documentation/styleguide/word_list.md b/doc/development/documentation/styleguide/word_list.md index 2c435cdc69d..c38c6586c3a 100644 --- a/doc/development/documentation/styleguide/word_list.md +++ b/doc/development/documentation/styleguide/word_list.md @@ -89,6 +89,14 @@ For example: Do not use title case **GitLab Agent** or **GitLab Agent for Kubernetes**. +## agent access token + +The token generated when you create an agent for Kubernetes. Use **agent access token**, not: + +- registration token +- secret token +- authentication token + ## allow, enable Try to avoid **allow** and **enable**, unless you are talking about security-related features. @@ -174,8 +182,7 @@ See also [contractions](index.md#contractions). Use one word for **checkbox**. Do not use **check box**. -You **select** (not **check** or **enable**) and **clear** (not **deselect** or **disable**) checkboxes. -For example: +You **select** (not **check** or **enable**) and **clear** (not **deselect** or **disable**) checkboxes. For example: - Select the **Protect environment** checkbox. - Clear the **Protect environment** checkbox. @@ -185,6 +192,8 @@ If you must refer to the checkbox, you can say it is selected or cleared. For ex - Ensure the **Protect environment** checkbox is cleared. - Ensure the **Protect environment** checkbox is selected. +(For `deselect`, [Vale](../testing.md#vale) rule: [`SubstitutionWarning.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/SubstitutionWarning.yml)) + ## checkout, check out Use **check out** as a verb. For the Git command, use `checkout`. @@ -201,10 +210,6 @@ 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. @@ -256,6 +261,11 @@ Do not use **Developer permissions**. A user who is assigned the Developer role See [the Microsoft style guide](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/d/disable-disabled) for guidance on **disable**. Use **inactive** or **off** instead. ([Vale](../testing.md#vale) rule: [`InclusionAbleism.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionAbleism.yml)) + +## disallow + +Use **prevent** instead of **disallow**. ([Vale](../testing.md#vale) rule: [`Substitutions.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/Substitutions.yml)) + ## dropdown list Use **dropdown list** to refer to the UI element. Do not use **dropdown** without **list** after it. @@ -667,6 +677,10 @@ Do not use [**roles**](#roles) and **permissions** interchangeably. Each user is Permissions are not the same as [**access levels**](#access-level). +## personal access token + +Use lowercase for **personal access token**. + ## please Do not use **please**. For details, see the [Microsoft style guide](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/p/please). @@ -951,6 +965,17 @@ One exception: You can use **we recommend** instead of **it is recommended** or Do not use **whitelist**. Another option is **allowlist**. ([Vale](../testing.md#vale) rule: [`InclusionCultural.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionCultural.yml)) +## yet + +Do not use **yet** when talking about the product or its features. The documentation describes the product as it is today. + +Sometimes you might need to use **yet** when writing a task. If you use +**yet**, ensure the surrounding phrases are written +in present tense, active voice. + +[View guidance about how to write about future features](index.md#promising-features-in-future-versions). +([Vale](../testing.md#vale) rule: [`CurrentStatus.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/CurrentStatus.yml)) + ## you, your, yours Use **you**, **your**, and **yours** instead of [**the user** and **the user's**](#user-users). diff --git a/doc/development/documentation/testing.md b/doc/development/documentation/testing.md index 905b44823c3..49fe0aff3c6 100644 --- a/doc/development/documentation/testing.md +++ b/doc/development/documentation/testing.md @@ -128,7 +128,7 @@ 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 +[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 @@ -213,19 +213,19 @@ You can use Vale: #### Vale result types -Vale returns three types of results: `suggestion`, `warning`, and `error`: +Vale returns three types of results: -- **Suggestion**-level results are writing tips and aren't displayed in CI - job output. Suggestions don't break CI. See a list of - [suggestion-level rules](https://gitlab.com/search?utf8=✓&snippets=false&scope=&repository_ref=master&search=path%3Adoc%2F.vale%2Fgitlab+Suggestion%3A&group_id=9970&project_id=278964). -- **Warning**-level results are [Style Guide](styleguide/index.md) violations, aren't displayed in CI - job output, and should contain clear explanations of how to resolve the warning. - Warnings may be technical debt, or can be future error-level test items - (after the Technical Writing team completes its cleanup). Warnings don't break CI. See a list of - [warning-level rules](https://gitlab.com/search?utf8=✓&snippets=false&scope=&repository_ref=master&search=path%3Adoc%2F.vale%2Fgitlab+Warning%3A&group_id=9970&project_id=278964). -- **Error**-level results are Style Guide violations, and should contain clear explanations - of how to resolve the error. Errors break CI and are displayed in CI job output. See a list of - [error-level rules](https://gitlab.com/search?utf8=✓&snippets=false&scope=&repository_ref=master&search=path%3Adoc%2F.vale%2Fgitlab+Error%3A&group_id=9970&project_id=278964). +- **Error** - For branding and trademark issues, and words or phrases with ambiguous meanings. +- **Warning** - For Technical Writing team style preferences. +- **Suggestion** - For basic technical writing tenets and best practices. + +The result types have these attributes: + +| Result type | Displayed in CI/CD job output | Causes CI/CD jobs to fail | Vale rule link | +|--------------|-------------------------------|---------------------------|----------------| +| `error` | **{check-circle}** Yes | **{check-circle}** Yes | [Error-level Vale rules](https://gitlab.com/search?utf8=✓&snippets=false&scope=&repository_ref=master&search=path%3Adoc%2F.vale%2Fgitlab+Error%3A&group_id=9970&project_id=278964) | +| `warning` | **{dotted-circle}** No | **{dotted-circle}** No | [Warning-level Vale rules](https://gitlab.com/search?utf8=✓&snippets=false&scope=&repository_ref=master&search=path%3Adoc%2F.vale%2Fgitlab+Warning%3A&group_id=9970&project_id=278964) | +| `suggestion` | **{dotted-circle}** No | **{dotted-circle}** No | [Suggestion-level Vale rules](https://gitlab.com/search?utf8=✓&snippets=false&scope=&repository_ref=master&search=path%3Adoc%2F.vale%2Fgitlab+Suggestion%3A&group_id=9970&project_id=278964) | #### Vale spelling test @@ -270,12 +270,10 @@ build pipelines: [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 - `brew` for macOS, run: +1. Install [`vale`](https://github.com/errata-ai/vale/releases). To install for: - ```shell - brew install vale - ``` + - macOS using `brew`, run: `brew install vale`. + - Linux, use your distribution's package manager or a [released binary](https://github.com/errata-ai/vale/releases). These tools can be [integrated with your code editor](#configure-editors). @@ -313,6 +311,9 @@ To configure Vale in your editor, install one of the following as appropriate: - 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). - Vim [ALE plugin](https://github.com/dense-analysis/ale). +- Jetbrains IDEs - No plugin exists, but + [this issue comment](https://github.com/errata-ai/vale-server/issues/39#issuecomment-751714451) + contains tips for configuring an external tool. - Emacs [Flycheck extension](https://github.com/flycheck/flycheck). This requires some configuration: |