diff options
author | Robert Speicher <rspeicher@gmail.com> | 2021-01-20 13:34:23 -0600 |
---|---|---|
committer | Robert Speicher <rspeicher@gmail.com> | 2021-01-20 13:34:23 -0600 |
commit | 6438df3a1e0fb944485cebf07976160184697d72 (patch) | |
tree | 00b09bfd170e77ae9391b1a2f5a93ef6839f2597 /doc/development/documentation | |
parent | 42bcd54d971da7ef2854b896a7b34f4ef8601067 (diff) | |
download | gitlab-ce-6438df3a1e0fb944485cebf07976160184697d72.tar.gz |
Add latest changes from gitlab-org/gitlab@13-8-stable-eev13.8.0-rc42
Diffstat (limited to 'doc/development/documentation')
-rw-r--r-- | doc/development/documentation/feature_flags.md | 8 | ||||
-rw-r--r-- | doc/development/documentation/index.md | 18 | ||||
-rw-r--r-- | doc/development/documentation/styleguide/index.md | 77 | ||||
-rw-r--r-- | doc/development/documentation/testing.md | 12 |
4 files changed, 67 insertions, 48 deletions
diff --git a/doc/development/documentation/feature_flags.md b/doc/development/documentation/feature_flags.md index 59298c5345f..7547ec59fb2 100644 --- a/doc/development/documentation/feature_flags.md +++ b/doc/development/documentation/feature_flags.md @@ -37,12 +37,10 @@ therefore, it indicates that it cannot be done by regular users of GitLab.com. ### Features disabled by default -For features disabled by default, if they cannot be used yet due to lack of -completeness, or if they're still under internal evaluation (for example, for -performance implications) do **not document them**: add (or merge) the docs -only when the feature is safe and ready to use and test by end-users. +For features disabled by default, add or improve the docs with every change in line with the +[definition of done](../contributing/merge_request_workflow.md#definition-of-done). -For feature flags disabled by default, if they can be used by end users: +Include details of the feature flag in the documentation: - Say that it's disabled by default. - Say whether it's enabled on GitLab.com. diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index 5fb5e9b433a..55f5d43b175 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -173,7 +173,7 @@ There are two types of redirects: - Redirect files added into the docs themselves, for users who view the docs in `/help` on self-managed instances. For example, [`/help` on GitLab.com](https://gitlab.com/help). - Redirects in a [`_redirects`](../../user/project/pages/redirects.md) file, for users - who view the docs on <http://docs.gitlab.com>. + who view the docs on <https://docs.gitlab.com>. To add a redirect: @@ -201,6 +201,9 @@ To add a redirect: 1. If the document being moved has any Disqus comments on it, follow the steps described in [Redirections for pages with Disqus comments](#redirections-for-pages-with-disqus-comments). + 1. If a documentation page you're removing includes images that aren't used + with any other documentation pages, be sure to use your MR to delete + those images from the repository. 1. Assign the MR to a technical writer for review and merge. 1. If the redirect is to one of the 4 internal docs projects (not an external URL), create an MR in [`gitlab-docs`](https://gitlab.com/gitlab-org/gitlab-docs): @@ -366,6 +369,19 @@ You can combine one or more of the following: = link_to 'Help page', help_page_path('user/permissions') ``` +#### Linking to `/help` in JavaScript + +To link to the documentation from a JavaScript or a Vue component, use the `helpPagePath` function from [`help_page_helper.js`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/assets/javascripts/helpers/help_page_helper.js): + +```javascript +import { helpPagePath } from '~/helpers/help_page_helper'; + +helpPagePath('user/permissions', { anchor: 'anchor-link' }) +// evaluates to '/help/user/permissions#anchor-link' for GitLab.com +``` + +This is preferred over static paths, as the helper also works on instances installed under a [relative URL](../../install/relative_url.md). + ### GitLab `/help` tests Several [RSpec tests](https://gitlab.com/gitlab-org/gitlab/blob/master/spec/features/help_pages_spec.rb) diff --git a/doc/development/documentation/styleguide/index.md b/doc/development/documentation/styleguide/index.md index 971652f76d3..bba94c7de7e 100644 --- a/doc/development/documentation/styleguide/index.md +++ b/doc/development/documentation/styleguide/index.md @@ -22,7 +22,7 @@ You can also view a list of [recent updates to this guide](https://gitlab.com/da If you can't find what you need: - View the GitLab Handbook for [writing style guidelines](https://about.gitlab.com/handbook/communication/#writing-style-guidelines) that apply to all GitLab content. -- Refer to one of the following: +- Refer to: - [Microsoft Style Guide](https://docs.microsoft.com/en-us/style-guide/welcome/). - [Google Developer Documentation Style Guide](https://developers.google.com/style). @@ -161,7 +161,7 @@ Markdown rendering engine. For a complete Kramdown reference, see the The [`gitlab-kramdown`](https://gitlab.com/gitlab-org/gitlab_kramdown) Ruby gem plans to support all [GitLab Flavored Markdown](../../../user/markdown.md) in the future, which is all Markdown supported for display in the GitLab application itself. For now, use -regular Markdown, following the rules in the linked style guide. +regular Markdown and follow the rules in the linked style guide. Kramdown-specific markup (for example, `{:.class}`) doesn't render properly on GitLab instances under [`/help`](../index.md#gitlab-help). @@ -207,9 +207,9 @@ Some examples fail if incorrect capitalization is used: Additionally, commands, parameters, values, filenames, and so on must be included in backticks. For example: -- "Change the `needs` keyword in your `.gitlab.yml`..." - - `needs` is a parameter, and `.gitlab.yml` is a file, so both need backticks. - Additionally, `.gitlab.yml` without backticks fails markdownlint because it +- "Change the `needs` keyword in your `.gitlab-ci.yml`..." + - `needs` is a parameter, and `.gitlab-ci.yml` is a file, so both need backticks. + Additionally, `.gitlab-ci.yml` without backticks fails markdownlint because it does not have capital G or L. - "Run `git clone` to clone a Git repository..." - `git clone` is a command, so it must be lowercase, while Git is the product, @@ -252,7 +252,7 @@ Put files for a specific product area into the related folder: ### Work with directories and files -Refer to the following items when working 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. @@ -332,7 +332,7 @@ GitLab documentation should be clear and easy to understand. ### Trademark Only use the GitLab name and trademarks in accordance with -[GitLab Brand Guidelines](https://about.gitlab.com/handbook/marketing/inbound-marketing/digital-experience/brand-guidelines/#trademark). +[GitLab Brand Guidelines](https://about.gitlab.com/handbook/marketing/corporate-marketing/brand-activation/brand-guidelines/#trademark). Don't use the possessive form of the word GitLab (`GitLab's`). @@ -412,7 +412,7 @@ references to user interface elements. For example: ### Inclusive language We strive to create documentation that's inclusive. This section includes -guidance and examples for the following categories: +guidance and examples for these categories: - [Gender-specific wording](#avoid-gender-specific-wording). (Tested in [`InclusionGender.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionGender.yml).) @@ -481,7 +481,7 @@ more precise and functional, such as `primary` and `secondary`. <!-- vale gitlab.InclusionCultural = YES --> -For more information see the following [Internet Draft specification](https://tools.ietf.org/html/draft-knodel-terminology-02). +For more information see the [Internet Draft specification](https://tools.ietf.org/html/draft-knodel-terminology-02). ### Fake user information @@ -499,7 +499,8 @@ addresses and names, do use: When including sample URLs in the documentation, use: - `example.com` when the domain name is generic. -- `gitlab.example.com` when referring to self-managed instances of GitLab. +- `gitlab.example.com` when referring only to self-managed GitLab instances. + Use `gitlab.com` for GitLab SaaS instances. ### Fake tokens @@ -507,12 +508,11 @@ There may be times where a token is needed to demonstrate an API call using cURL or a variable used in CI. It is strongly advised not to use real tokens in documentation even if the probability of a token being exploited is low. -You can use the following fake tokens as examples: +You can use these fake tokens as examples: | Token type | Token value | |:----------------------|:-------------------------------------------------------------------| -| Private user token | `<your_access_token>` | -| Personal access token | `n671WNGecHugsdEDPsyo` | +| Personal access token | `<your_access_token>` | | Application ID | `2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6` | | Application secret | `04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df` | | CI/CD variable | `Li8j-mLUVA3eZYjPfd_H` | @@ -526,11 +526,14 @@ You can use the following fake tokens as examples: ### Usage list <!-- vale off --> -| Usage | Guidance | -|-----------------------|-----| -| admin, admin area | Use **administration**, **administrator**, **administer**, or **Admin Area** instead. |. +| Usage | Guidance | +|-----------------------|----------| +| above | Try to avoid extra words when referring to an example or table in a documentation page, but if required, use **previously** instead. | +| admin, admin area | Use **administration**, **administrator**, **administer**, or **Admin Area** instead. ([Vale](../testing.md#vale) rule: [`Admin.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/Admin.yml)) | +| allow, enable | Try to avoid, unless you are talking about security-related features. For example, instead of "This feature allows you to create a pipeline," use "Use this feature to create a pipeline." This phrasing is more active and is from the user perspective, rather than the person who implemented the feature. [View details](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/a/allow-allows). | | and/or | Use **or** instead, or another sensible construction. | -| currently | Do not use when talking about the product or its features. The documentation describes the product as it is today. | +| below | Try to avoid extra words when referring to an example or table in a documentation page, but if required, use **following** instead. | +| currently | Do not use when talking about the product or its features. The documentation describes the product as it is today. ([Vale](../testing.md#vale) rule: [`CurrentStatus.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/CurrentStatus.yml)) | | easily | Do not use. If the user doesn't find the process to be these things, we lose their trust. | | e.g. | Do not use Latin abbreviations. Use **for example**, **such as**, **for instance**, or **like** instead. ([Vale](../testing.md#vale) rule: [`LatinTerms.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/LatinTerms.yml)) | | future tense | When possible, use present tense instead. For example, use `after you execute this command, GitLab displays the result` instead of `after you execute this command, GitLab will display the result`. ([Vale](../testing.md#vale) rule: [`FutureTense.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/FutureTense.yml)) | @@ -865,7 +868,7 @@ Consider installing a plugin or extension in your editor for formatting tables: When creating tables of lists of features (such the features available to each role on the [Permissions](../../../user/permissions.md#project-members-permissions) -page), use the following phrases: +page), use these phrases: | Option | Markdown | Displayed result | |--------|--------------------------|------------------------| @@ -967,7 +970,7 @@ Links are important in GitLab documentation. They allow you to [link instead of summarizing](#link-instead-of-summarize) to help preserve a [single source of truth](#why-a-single-source-of-truth) in GitLab documentation. -We include guidance for links in the following categories: +We include guidance for links in these categories: - How to set up [anchor links](#anchor-links) for headings. - How to set up [criteria](#basic-link-criteria) for configuring a link. @@ -1137,14 +1140,14 @@ When documenting navigation through the user interface: - Use the exact wording as shown in the UI, including any capital letters as-is. - Use bold text for navigation items and the char "greater than" (`>`) as a - separator. For example: `Navigate to your project's **Settings > CI/CD**`. + separator. For example: `From your project, go to **Settings > CI/CD**`. - If there are any expandable menus, make sure to mention that the user needs to expand the tab to find the settings you're referring to. For example: - `Navigate to your project's **Settings > CI/CD** and expand **General pipelines**`. + `From your group, go to **Settings > CI/CD** and expand **General pipelines**`. ### Navigational elements -Use the following terms when referring to the main GitLab user interface +Use these terms when referring to the main GitLab user interface elements: - **Top menu**: This is the top menu that spans the width of the user interface. @@ -1183,7 +1186,7 @@ When you take screenshots: - Save the image with a lowercase filename that's descriptive of the feature or concept in the image. If the image is of the GitLab interface, append the - GitLab version to the filename, based on the following format: + GitLab version to the filename, based on this format: `image_name_vX_Y.png`. For example, for a screenshot taken from the pipelines page of GitLab 11.1, a valid name is `pipelines_v11_1.png`. If you're adding an illustration that doesn't include parts of the user interface, add the release @@ -1365,7 +1368,7 @@ hidden on the documentation site, but is displayed by `/help`. <!-- vale on --> Syntax highlighting is required for fenced code blocks added to the GitLab -documentation. Refer to the following table for the most common language classes, +documentation. Refer to this table for the most common language classes, or check the [complete list](https://github.com/rouge-ruby/rouge/wiki/List-of-supported-languages-and-lexers) of available language classes: @@ -1433,15 +1436,15 @@ Usage examples: Icons should be used sparingly, and only in ways that aid and do not hinder the readability of the text. -For example, the following adds little to the accompanying text: +For example, this Markdown adds little to the accompanying text: ```markdown -1. Go to **{home}** **Project overview > Details** +1. Go to **{home}** **Project overview > Details**. ``` -1. Go to **{home}** **Project overview > Details** +1. Go to **{home}** **Project overview > Details**. -However, the following might help the reader connect the text to the user +However, these tables might help the reader connect the text to the user interface: ```markdown @@ -1555,14 +1558,12 @@ It renders on the GitLab documentation site as: ## Terms -To maintain consistency through GitLab documentation, the following guides -documentation authors on agreed styles and usage of terms. +To maintain consistency through GitLab documentation, use these styles and terms. ### Merge requests (MRs) Merge requests allow you to exchange changes you made to source code and -collaborate with other people on the same project. This term is used in -the following ways: +collaborate with other people on the same project. - Use lowercase _merge requests_ regardless of whether referring to the feature or individual merge requests. @@ -1580,7 +1581,7 @@ Examples: ### Describe UI elements -The following are styles to follow when describing user interface elements in an +Follow these styles when you're describing user interface elements in an application: - For elements with a visible label, use that label in bold with matching case. @@ -1590,7 +1591,7 @@ application: ### Verbs for UI elements -The following are recommended verbs for specific uses with user interface +Use these verbs for specific uses with user interface elements: | Recommended | Used for | Replaces | @@ -1637,7 +1638,7 @@ displayed for the page or feature. #### Version text in the **Version History** -If all content in a section is related, add version text following the header +If all content in a section is related, add version text after the header for the section. The version information must be surrounded by blank lines, and each entry should be on its own line. @@ -1670,8 +1671,8 @@ the blockquote to use a bulleted list: If a feature is moved to another tier: ```markdown -> - [Moved](<link-to-issue>) from [GitLab Premium](https://about.gitlab.com/pricing/) to [GitLab Starter](https://about.gitlab.com/pricing/) in 11.8. -> - [Moved](<link-to-issue>) from [GitLab Starter](https://about.gitlab.com/pricing/) to GitLab Core in 12.0. +> - [Moved](<link-to-issue>) from GitLab Premium to GitLab Starter in 11.8. +> - [Moved](<link-to-issue>) from GitLab Starter to GitLab Core in 12.0. ``` If a feature is deprecated, include a link to a replacement (when available): @@ -1709,7 +1710,7 @@ voters to agree. #### End-of-life for features or products When a feature or product enters its end-of-life, indicate its status by -creating a [warning alert](#alert-boxes) directly following its relevant header. +creating a [warning alert](#alert-boxes) directly after its relevant header. If possible, link to its deprecation and removal issues. For example: diff --git a/doc/development/documentation/testing.md b/doc/development/documentation/testing.md index d2e3f473532..561727648f0 100644 --- a/doc/development/documentation/testing.md +++ b/doc/development/documentation/testing.md @@ -183,7 +183,8 @@ Vale configuration is found in the following projects: - [`charts`](https://gitlab.com/gitlab-org/charts/gitlab/-/tree/master/doc/.vale/gitlab) - [`gitlab-development-kit`](https://gitlab.com/gitlab-org/gitlab-development-kit/-/tree/master/doc/.vale/gitlab) -This configuration is also used within build pipelines. +This configuration is also used within build pipelines, where +[error-level rules](#vale-result-types) are enforced. You can use Vale: @@ -197,14 +198,17 @@ You can use Vale: Vale returns three types of results: `suggestion`, `warning`, and `error`: - **Suggestion**-level results are writing tips and aren't displayed in CI - job output. Suggestions don't break 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. + (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 about how to resolve the error. Errors break CI and are displayed in CI job output. - of how to resolve the error. Errors break CI and are displayed in CI job output. + 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). ### Install linters |