diff options
Diffstat (limited to 'doc/development/documentation')
17 files changed, 592 insertions, 513 deletions
diff --git a/doc/development/documentation/feature_flags.md b/doc/development/documentation/feature_flags.md index 89e54183e50..87d2930dcb5 100644 --- a/doc/development/documentation/feature_flags.md +++ b/doc/development/documentation/feature_flags.md @@ -24,7 +24,8 @@ When you document feature flags, you must: ## Add version history text -When the state of a flag changes (for example, disabled by default to enabled by default), add the change to the version history. +When the state of a flag changes (for example, disabled by default to enabled by default), add the change to the +[version history](versions.md#add-a-version-history-item). Possible version history entries are: diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index ee439e93011..73c1874f09e 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w description: Learn how to contribute to GitLab Documentation. --- -# GitLab Documentation guidelines +# GitLab documentation 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. @@ -42,7 +42,7 @@ run only the jobs that match the type of contribution. If your contribution cont **only** documentation changes, then only documentation-related jobs run, and the pipeline completes much faster than a code contribution. -If you are submitting documentation-only changes to Omnibus or Charts, +If you are submitting documentation-only changes to Omnibus, Charts, or Operator, the fast pipeline is not determined automatically. Instead, create branches for docs-only merge requests using the following guide: @@ -240,9 +240,9 @@ Every GitLab instance includes documentation at `/help` (`https://gitlab.example 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). +hour 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. +in an hour 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 @@ -380,6 +380,47 @@ is made, Danger Bot leaves a comment with further instructions about the documen process. This is configured in the `Dangerfile` in the GitLab repository under [/danger/documentation/](https://gitlab.com/gitlab-org/gitlab/-/tree/master/danger/documentation). +## Help and feedback section + +This section ([introduced](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/319) in GitLab 11.4) +is displayed at the end of each document and can be omitted by adding a key into +the front matter: + +```yaml +--- +feedback: false +--- +``` + +The default is to leave it there. If you want to omit it from a document, you +must check with a technical writer before doing so. + +## Disqus + +We have integrated the docs site with Disqus (introduced by +[!151](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/151)), +allowing our users to post comments. + +To omit only the comments from the feedback section, use the following key in +the front matter: + +```yaml +--- +comments: false +--- +``` + +We're hiding comments only in main index pages, such as [the main documentation index](../../index.md), +since its content is too broad to comment on. Before omitting Disqus, you must +check with a technical writer. + +Note that after adding `feedback: false` to the front matter, it will omit +Disqus, therefore, don't add both keys to the same document. + +The click events in the feedback section are tracked with Google Tag Manager. +The conversions can be viewed on Google Analytics by navigating to +**Behavior > Events > Top events > docs**. + ## Automatic screenshot generator You can now set up an automatic screenshot generator to take and compress screenshots with the diff --git a/doc/development/documentation/redirects.md b/doc/development/documentation/redirects.md index 4c748924c67..1bc697f2878 100644 --- a/doc/development/documentation/redirects.md +++ b/doc/development/documentation/redirects.md @@ -16,12 +16,7 @@ description: Learn how to contribute to GitLab Documentation. # Redirects in GitLab documentation When you move, rename, or delete a page, you must add a redirect. Redirects reduce -how often users get 404s when visiting the documentation site from out-of-date links, like: - -- Bookmarks -- Links from external sites -- Links from old blog posts -- Links in the documentation site global navigation +how often users get 404s when they visit the documentation site from out-of-date links. Add a redirect to ensure: @@ -36,9 +31,11 @@ Add a redirect to ensure: Be sure to assign a technical writer to any merge request that moves, renames, or deletes a page. Technical Writers can help with any questions and can review your change. +## Types of redirects + There are two types of redirects: -- [Redirect added into the documentation files themselves](#add-a-redirect), for users who +- [Redirects added into the documentation files themselves](#redirect-to-a-page-that-already-exists), for users who view the docs in `/help` on self-managed instances. For example, [`/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 @@ -52,96 +49,109 @@ 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 +## Redirect to a page that already exists + +To redirect a page to another page in the same repository: + +1. In the Markdown file that you want to direct to a new location: + + - Delete all of the content. + - Add this content: + + ```markdown + --- + redirect_to: '../newpath/to/file/index.md' + remove_date: 'YYYY-MM-DD' + --- + + This document was moved to [another location](../path/to/file/index.md). + + <!-- This redirect file can be deleted after <YYYY-MM-DD>. --> + <!-- 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 both instances of `YYYY-MM-DD` with the expiration date, as explained in the template. + +1. If the page has Disqus comments, follow [the steps for pages with Disqus comments](#redirections-for-pages-with-disqus-comments). +1. If the page had images that aren't used on any other pages, delete them. -NOTE: -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). +After your changes are committed, search for and update all links that point to the old file: -To add a redirect: +- In <https://gitlab.com/gitlab-com/www-gitlab-com>, search for full URLs: -1. In the repository (`gitlab`, `gitlab-runner`, `omnibus-gitlab`, or `charts`), - create a new documentation file. Don't delete the old one. The easiest - way is to copy it. For example: + ```shell + grep -r "docs.gitlab.com/ee/path/to/file.html" . + ``` - ```shell - cp doc/user/search/old_file.md doc/api/new_file.md +- In <https://gitlab.com/gitlab-org/gitlab-docs/-/tree/master/content/_data>, + search the navigation bar configuration files for the path with `.html`: + + ```shell + grep -r "path/to/file.html" . ``` -1. Add the redirect code to the old documentation file by running the - following Rake task. The first argument is the path of the old file, - and the second argument is the path of the new file: +- In any of the four internal projects, search for links in the docs + and codebase. Search for all variations, including full URL and just the path. + For example, go to the root directory of the `gitlab` project and run: - - To redirect to a page in the same project, use relative paths and - the `.md` extension. Both old and new paths start from the same location. - In the following example, both paths are relative to `doc/`: + ```shell + grep -r "docs.gitlab.com/ee/path/to/file.html" . + grep -r "path/to/file.html" . + grep -r "path/to/file.md" . + grep -r "path/to/file" . + ``` - ```shell - bundle exec rake "gitlab:docs:redirect[doc/user/search/old_file.md, doc/api/new_file.md]" - ``` + You might need to try variations of relative links, such as `../path/to/file` or + `../file` to find every case. - - To redirect to a page in a different project or site, use the full URL (with `https://`) : +### Move a file's location - ```shell - bundle exec rake "gitlab:docs:redirect[doc/user/search/old_file.md, https://example.com]" - ``` +If you want to move a file from one location to another, you do not move it. +Instead, you duplicate the file, and add the redirect code to the old file. - - Alternatively, you can omit the arguments and be prompted to enter the values: +1. Create the new file. +1. Copy the contents of the old file to the new one. +1. In the old file, delete all the content. +1. In the old file, add the redirect code and follow the rest of the steps in + the [Redirect to a page that already exists](#redirect-to-a-page-that-already-exists) topic. - ```shell - bundle exec rake gitlab:docs:redirect - ``` +## Use code to add a redirect - If you don't want to use the Rake task, you can use the following template: +If you prefer to use a script to create the redirect: - ```markdown - --- - redirect_to: '../newpath/to/file/index.md' - remove_date: 'YYYY-MM-DD' - --- +Add the redirect code to the old documentation file by running the +following Rake task. The first argument is the path of the old file, +and the second argument is the path of the new file: - This document was moved to [another location](../path/to/file/index.md). +- To redirect to a page in the same project, use relative paths and + the `.md` extension. Both old and new paths start from the same location. + In the following example, both paths are relative to `doc/`: - <!-- This redirect file can be deleted after <YYYY-MM-DD>. --> - <!-- 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 --> - ``` + ```shell + bundle exec rake "gitlab:docs:redirect[doc/user/search/old_file.md, doc/api/new_file.md]" + ``` - - 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 - you're removing includes images that aren't used - with any other documentation pages, be sure to use your merge request to delete - those images from the repository. -1. Assign the merge request to a technical writer for review and merge. -1. Search for links to the old documentation file. You must find and update all - links that point to the old documentation file: - - - In <https://gitlab.com/gitlab-com/www-gitlab-com>, search for full URLs: - `grep -r "docs.gitlab.com/ee/path/to/file.html" .` - - In <https://gitlab.com/gitlab-org/gitlab-docs/-/tree/master/content/_data>, - search the navigation bar configuration files for the path with `.html`: - `grep -r "path/to/file.html" .` - - In any of the four internal projects, search for links in the docs - and codebase. Search for all variations, including full URL and just the path. - For example, go to the root directory of the `gitlab` project and run: - - ```shell - grep -r "docs.gitlab.com/ee/path/to/file.html" . - grep -r "path/to/file.html" . - grep -r "path/to/file.md" . - grep -r "path/to/file" . - ``` +- To redirect to a page in a different project or site, use the full URL (with `https://`) : + + ```shell + bundle exec rake "gitlab:docs:redirect[doc/user/search/old_file.md, https://example.com]" + ``` + +- Alternatively, you can omit the arguments and be prompted to enter the values: + + ```shell + bundle exec rake gitlab:docs:redirect + ``` + +## Redirecting a page created before the release + +If you create a new page and then rename it before it's added to a release on the 18th: - You may need to try variations of relative links, such as `../path/to/file` or - `../file` to find every case. +Instead of following that procedure, 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). ## Redirections for pages with Disqus comments diff --git a/doc/development/documentation/restful_api_styleguide.md b/doc/development/documentation/restful_api_styleguide.md index bf1461a810d..2991c1b3224 100644 --- a/doc/development/documentation/restful_api_styleguide.md +++ b/doc/development/documentation/restful_api_styleguide.md @@ -59,12 +59,12 @@ METHOD /endpoint Supported attributes: -| Attribute | Type | Required | Description | -|:-------------------------|:---------|:-----------------------|:----------------------| -| `attribute` | datatype | **{check-circle}** Yes | Detailed description. | -| `attribute` **(<tier>)** | datatype | **{dotted-circle}** No | Detailed description. | -| `attribute` | datatype | **{dotted-circle}** No | Detailed description. | -| `attribute` | datatype | **{dotted-circle}** No | Detailed description. | +| Attribute | Type | Required | Description | +|:-------------------------|:---------|:---------|:----------------------| +| `attribute` | datatype | Yes | Detailed description. | +| `attribute` **(<tier>)** | datatype | No | Detailed description. | +| `attribute` | datatype | No | Detailed description. | +| `attribute` | datatype | No | Detailed description. | If successful, returns [`<status_code>`](../../api/index.md#status-codes) and the following response attributes: @@ -123,13 +123,13 @@ To deprecate an attribute: 1. Add inline deprecation text to the description. ```markdown - | Attribute | Type | Required | Description | - |:--------------|:-------|:-----------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------| - | `widget_name` | string | **{dotted-circle}** No | [Deprecated](<link-to-issue>) in GitLab 14.7 and is planned for removal in 15.4. Use `widget_id` instead. The name of the widget. | + | Attribute | Type | Required | Description | + |:--------------|:-------|:---------|:----------------------------------------------------------------------------------------------------------------------------------------------------| + | `widget_name` | string | No | [Deprecated](<link-to-issue>) in GitLab 14.7 and is planned for removal in 15.4. Use `widget_id` instead. The name of the widget. | ``` To widely announce a deprecation, or if it's a breaking change, -[update the deprecations and removals documentation](../deprecation_guidelines/#update-the-deprecations-and-removals-documentation). +[update the deprecations and removals documentation](../deprecation_guidelines/index.md#update-the-deprecations-and-removals-documentation). ## Method description @@ -139,20 +139,20 @@ always be in code blocks using backticks (`` ` ``). Sort the table by required attributes first, then alphabetically. ```markdown -| Attribute | Type | Required | Description | -|:-----------------------------|:--------------|:-----------------------|:----------------------------------------------------| -| `title` | string | **{check-circle}** Yes | Title of the issue. | -| `assignee_ids` **(PREMIUM)** | integer array | **{dotted-circle}** No | IDs of the users to assign the issue to. | -| `confidential` | boolean | **{dotted-circle}** No | Sets the issue to confidential. Default is `false`. | +| Attribute | Type | Required | Description | +|:-----------------------------|:--------------|:---------|:----------------------------------------------------| +| `title` | string | Yes | Title of the issue. | +| `assignee_ids` **(PREMIUM)** | integer array | No | IDs of the users to assign the issue to. | +| `confidential` | boolean | No | Sets the issue to confidential. Default is `false`. | ``` Rendered example: -| Attribute | Type | Required | Description | -|:-----------------------------|:--------------|:-----------------------|:----------------------------------------------------| -| `title` | string | **{check-circle}** Yes | Title of the issue. | -| `assignee_ids` **(PREMIUM)** | integer array | **{dotted-circle}** No | IDs of the users to assign the issue to. | -| `confidential` | boolean | **{dotted-circle}** No | Sets the issue to confidential. Default is `false`. | +| Attribute | Type | Required | Description | +|:-----------------------------|:--------------|:---------|:----------------------------------------------------| +| `title` | string | Yes | Title of the issue. | +| `assignee_ids` **(PREMIUM)** | integer array | No | IDs of the users to assign the issue to. | +| `confidential` | boolean | No | Sets the issue to confidential. Default is `false`. | For information about writing attribute descriptions, see the [GraphQL API description style guide](../api_graphql_styleguide.md#description-style-guide). diff --git a/doc/development/documentation/review_apps.md b/doc/development/documentation/review_apps.md index 8cb9e6437b8..a50efceb307 100644 --- a/doc/development/documentation/review_apps.md +++ b/doc/development/documentation/review_apps.md @@ -57,7 +57,7 @@ If you want to know the in-depth details, here's what's really happening: The following GitLab features are used among others: - [Manual jobs](../../ci/jobs/job_control.md#create-a-job-that-must-be-run-manually) -- [Multi project pipelines](../../ci/pipelines/multi_project_pipelines.md) +- [Multi project pipelines](../../ci/pipelines/downstream_pipelines.md#multi-project-pipelines) - [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) diff --git a/doc/development/documentation/site_architecture/deployment_process.md b/doc/development/documentation/site_architecture/deployment_process.md index 5f6076f3195..8a9c2e1e8d7 100644 --- a/doc/development/documentation/site_architecture/deployment_process.md +++ b/doc/development/documentation/site_architecture/deployment_process.md @@ -144,18 +144,21 @@ graph LR ### Manually deploy to production -GitLab Docs is deployed to production whenever the `Build docs.gitlab.com every 4 hours` scheduled pipeline runs. By -default, this pipeline runs every four hours. +GitLab Docs is deployed to production whenever the `Build docs.gitlab.com every hour` scheduled pipeline runs. By +default, this pipeline runs every hour. Maintainers can [manually](../../../ci/pipelines/schedules.md#run-manually) run this pipeline to force a deployment to production: 1. Go to the [scheduled pipelines](https://gitlab.com/gitlab-org/gitlab-docs/-/pipeline_schedules) for `gitlab-docs`. -1. Next to `Build docs.gitlab.com every 4 hours`, select **Play** (**{play}**). +1. Next to `Build docs.gitlab.com every hour`, select **Play** (**{play}**). The updated documentation is available in production after the `pages` and `pages:deploy` jobs complete in the new pipeline. +If you do not have the Maintainer role to perform this task, ask for help in the +`#docs` Slack channel. + ## Docker files The [`dockerfiles` directory](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/dockerfiles/) contains all needed diff --git a/doc/development/documentation/site_architecture/index.md b/doc/development/documentation/site_architecture/index.md index 2864bbe7404..44e4aac2756 100644 --- a/doc/development/documentation/site_architecture/index.md +++ b/doc/development/documentation/site_architecture/index.md @@ -33,7 +33,7 @@ Then you can use one of these approaches: of the documentation in the external repository. The landing page is indexed and searchable on <https://docs.gitlab.com>, but the rest of the documentation is not. For example, the [GitLab Workflow extension for VS Code](../../../user/project/repository/vscode.md). - We do not encourage the use of [pages with lists of links](../structure.md#topics-and-resources-pages), + We do not encourage the use of [pages with lists of links](../topic_types/index.md#topics-and-resources), so only use this option if the recommended options are not feasible. ## Monthly release process (versions) diff --git a/doc/development/documentation/structure.md b/doc/development/documentation/structure.md index a5d1290a17a..35a93f08f66 100644 --- a/doc/development/documentation/structure.md +++ b/doc/development/documentation/structure.md @@ -1,395 +1,11 @@ --- -stage: none -group: Style Guide -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -description: What to include in GitLab documentation pages. +redirect_to: 'topic_types/index.md' +remove_date: '2022-11-16' --- -# Documentation topic types (CTRT) +This document was moved to [another location](topic_types/index.md). -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 (CTRT): - -- [Concept](#concept) -- [Task](#task) -- [Reference](#reference) -- [Troubleshooting](#troubleshooting) - -In general, each page in our docset contains multiple topics. (Each heading indicates a new topic.) -Each topic on a page should be a specific topic type. For example, -a page with the title `Pipelines` can include topics that are concepts and tasks. - -A page might also contain only one type of information. These pages are generally one of our -[other content types](#other-types-of-content). - -## Concept - -A concept introduces a single feature or concept. - -A concept should answer the questions: - -- What is this? -- Why would I use it? - -Think of everything someone might want to know if they've never heard of this concept before. - -Don't tell them **how** to do this thing. Tell them **what it is**. - -If you start describing another concept, start a new concept and link to it. - -Concepts should be in this format: - -```markdown -# Title (a noun, like "Widgets") - -A paragraph that explains what this thing is. - -Another paragraph that explains what this thing is. - -Remember, if you start to describe about another concept, stop yourself. -Each concept should be about one concept only. -``` - -### Concept headings - -For the heading text, use a noun. For example, `Widgets` or `GDK dependency management`. - -If a noun is ambiguous, you can add a gerund. For example, `Documenting versions` instead of `Versions`. - -Avoid these heading titles: - -- `Overview` or `Introduction`. Instead, use a more specific - noun or phrase that someone would search for. -- `Use cases`. Instead, incorporate the information as part of the concept. -- `How it works`. Instead, use a noun followed by `workflow`. For example, `Merge request workflow`. - -## Task - -A task gives instructions for how to complete a procedure. - -Tasks should be in this format: - -```markdown -# Title (starts with an active verb, like "Create a widget" or "Delete a widget") - -Do this task when you want to... - -Prerequisites (optional): - -- Thing 1 -- Thing 2 -- Thing 3 - -To do this task: - -1. Location then action. (Go to this menu, then select this item.) -1. Another step. -1. Another step. - -Task result (optional). Next steps (optional). -``` - -Here is an example. - -```markdown -# Create an issue - -Create an issue when you want to track bugs or future work. - -Prerequisites: - -- You must have at least the Developer role for the project. - -To create an issue: - -1. On the top bar, select **Menu > Projects** and find your project. -1. On the left sidebar, select **Issues > List**. -1. In the top right corner, select **New issue**. -1. Complete the fields. (If you have reference content that lists each field, link to it here.) -1. Select **Create issue**. - -The issue is created. You can view it by going to **Issues > List**. -``` - -### Task headings - -For the heading text, use the structure `active verb` + `noun`. -For example, `Create an issue`. - -If you have several tasks on a page that share prerequisites, you can use the title -`Prerequisites` and link to it. - -## Reference - -Reference information should be in an easily-scannable format, -like a table or list. It's similar to a dictionary or encyclopedia entry. - -```markdown -# Title (a noun, like "Pipeline settings" or "Administrator options") - -Introductory sentence. - -| Setting | Description | -|---------|-------------| -| **Name** | Descriptive sentence about the setting. | -``` - -### Reference headings - -Reference headings are usually nouns. - -Avoid these heading titles: - -- `Important notes`. Instead, incorporate this information - closer to where it belongs. For example, this information might be a prerequisite - for a task, or information about a concept. -- `Limitations`. Instead, move the content near other similar information. - If you must, you can use the title `Known issues`. - -## Troubleshooting - -Troubleshooting topics should be the last topics on a page. - -Troubleshooting can be one of three categories: - -- **An introductory topic.** This topic introduces the troubleshooting section of a page. - For example: - - ```markdown - ## Troubleshooting - - When working with <x feature>, you might encounter the following issues. - ``` - -- **Troubleshooting task.** The title should be similar to a [standard task](#task). - For example, "Run debug tools" or "Verify syntax." - -- **Troubleshooting reference.** This information includes the error message. For example: - - ```markdown - ### The error message or a description of it - - You might get an error that states <error message>. - - This issue occurs when... - - The workaround is... - ``` - - If multiple causes or workarounds exist, consider putting them into a table format. - If you use the exact error message, surround it in backticks so it's styled as code. - -If a page has more than five troubleshooting topics, put the content on a separate page that has troubleshooting information exclusively. Name the page `Troubleshooting <featurename>`. - -### Troubleshooting headings - -For the heading of a **Troubleshooting reference** topic: - -- Consider including at least a partial error message. -- Use fewer than 70 characters. - -If you do not put the full error in the title, include it in the body text. - -### Related topics - -If inline links are not sufficient, you can create a topic called **Related topics** -and include an unordered 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) -``` - -## General heading text guidelines - -In general, for heading text: - -- Be clear and direct. Make every word count. -- Use articles and prepositions. -- Follow [capitalization](styleguide/index.md#capitalization) guidelines. -- Do not repeat text from earlier headings. For example, if the page is about merge requests, - instead of `Troubleshooting merge requests`, use only `Troubleshooting`. - -See also [guidelines for headings in Markdown](styleguide/index.md#headings-in-markdown). - -## 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-ctrt). -These include: - -- [Tutorials](#tutorials) -- [Get started pages](#get-started) -- [Topics and resources pages](#topics-and-resources-pages) - -In most cases, these pages are standalone. - -### Tutorials - -A tutorial is an end-to-end walkthrough of a complex workflow or scenario. -In general, you might consider using a tutorial when: - -- The workflow requires a number of sequential steps where each step consists - of sub-steps. -- The steps cover a variety of GitLab features or third-party tools. - -Tutorials are learning aids that complement our core documentation. -They do not introduce new features. -Always use the primary [topic types](#documentation-topic-types-ctrt) to document new features. - -Tutorials should be in this format: - -```markdown -# Title (starts with "Tutorial:" followed by an active verb, like "Tutorial: Create a website") - -A paragraph that explains what the tutorial does, and the expected outcome. - -To create a website: - -1. [Do the first task](#do-the-first-task) -1. [Do the second task](#do-the-second-task) - -Prerequisites (optional): - -- Thing 1 -- Thing 2 -- Thing 3 - -## Do the first task - -To do step 1: - -1. First step. -1. Another step. -1. Another step. - -## Do the second task - -Before you begin, make sure you have [done the first task](#do-the-first-task). - -To do step 2: - -1. First step. -1. Another step. -1. Another step. -``` - -### Get started - -A get started page is a set of steps to help a user get set up -quickly to use a single GitLab feature or tool. -It might consist of more than one task. - -Get started pages should be in this format: - -```markdown -# Title ("Get started with <feature>") - -Complete the following steps to ... . - -1. First step. -1. Another step. -1. Another step. - -If you need to add more than one task, -consider using subsections for each distinct task. -``` - -### Topics and resources pages - -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. -Lists like this can get out of date quickly and offer little value to users. -We've included this type here because: - -- There are existing pages in the documentation that follow this format, - and they should be standardized. -- They can sometimes help navigate a complex section of the documentation. - -If you come across a page like this -or you have to create one, use this format: - -```markdown -# Title ("Topics and resources for <feature>") - -Brief sentence to describe the feature. - -Refer to these resources for more information about <this feature>: - -- Link 1 -- Link 2 -- Link 3 -``` - -## Help and feedback section - -This section ([introduced](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/319) in GitLab 11.4) -is displayed at the end of each document and can be omitted by adding a key into -the front matter: - -```yaml ---- -feedback: false ---- -``` - -The default is to leave it there. If you want to omit it from a document, you -must check with a technical writer before doing so. - -### Disqus - -We also have integrated the docs site with Disqus (introduced by -[!151](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/151)), -allowing our users to post comments. - -To omit only the comments from the feedback section, use the following key in -the front matter: - -```yaml ---- -comments: false ---- -``` - -We're hiding comments only in main index pages, such as [the main documentation index](../../index.md), -since its content is too broad to comment on. Before omitting Disqus, you must -check with a technical writer. - -Note that after adding `feedback: false` to the front matter, it will omit -Disqus, therefore, don't add both keys to the same document. - -The click events in the feedback section are tracked with Google Tag Manager. -The conversions can be viewed on Google Analytics by navigating to -**Behavior > Events > Top events > docs**. - -## Guidelines for good practices - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/36576/) in GitLab 13.2 as GitLab Development documentation. - -*Good practice* examples demonstrate encouraged ways of writing code while -comparing with examples of practices to avoid. These examples are labeled as -*Bad* or *Good*. In GitLab development guidelines, when presenting the cases, -it's recommended to follow a *first-bad-then-good* strategy. First demonstrate -the *Bad* practice (how things *could* be done, which is often still working -code), and then how things *should* be done better, using a *Good* example. This -is typically an improved example of the same code. - -Consider the following guidelines when offering examples: - -- First, offer the *Bad* example, and then the *Good* one. -- When only one bad case and one good case is given, use the same code block. -- When more than one bad case or one good case is offered, use separated code - blocks for each. With many examples being presented, a clear separation helps - the reader to go directly to the good part. Consider offering an explanation - (for example, a comment, or a link to a resource) on why something is bad - practice. -- Better and best cases can be considered part of the good cases' code block. - In the same code block, precede each with comments: `# Better` and `# Best`. - -Although the bad-then-good approach is acceptable for the GitLab development -guidelines, do not use it for user documentation. For user documentation, use -*Do* and *Don't*. For examples, see the [Pajamas Design System](https://design.gitlab.com/content/punctuation/). +<!-- This redirect file can be deleted after <2022-11-16>. --> +<!-- 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 -->
\ No newline at end of file diff --git a/doc/development/documentation/styleguide/index.md b/doc/development/documentation/styleguide/index.md index 709e6b2d0d9..bc79bf0fbe2 100644 --- a/doc/development/documentation/styleguide/index.md +++ b/doc/development/documentation/styleguide/index.md @@ -887,7 +887,7 @@ To be consistent, use these templates when you write navigation steps in a task To open project settings: ```markdown -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > CI/CD**. 1. Expand **General pipelines**. ``` @@ -895,7 +895,7 @@ To open project settings: To open group settings: ```markdown -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Settings > CI/CD**. 1. Expand **General pipelines**. ``` @@ -903,7 +903,7 @@ To open group settings: To open the Admin Area: ```markdown -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. ``` To select your avatar: @@ -950,7 +950,7 @@ Use the phrase **Complete the fields**. For example: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Repository**. 1. Expand **Push rules**. 1. Complete the fields. @@ -1361,6 +1361,48 @@ It renders on the GitLab documentation site as: > - This is a list item > - Second item in the list +## Tabs + +On the docs site, you can format text so it's displayed as tabs. + +To create a set of tabs, follow this example: + +```plaintext +::Tabs + +:::TabTitle Tab One + +Here's some content in tab one. + +:::TabTitle Tab Two + +Here's some other content in tab two. + +::EndTabs +``` + +This code renders on the GitLab documentation site as: + +::Tabs + +:::TabTitle Tab One + +Here's some content in tab one. + +:::TabTitle Tab Two + +Here's some other content in tab two. + +::EndTabs + +For tab titles, be brief and consistent. Ensure they are parallel, and start each with a capital letter. +For example: + +- `Omnibus package`, `Helm chart`, `Source` +- `15.1 and earlier`, `15.2 and later` + +See [Pajamas](https://design.gitlab.com/components/tabs/#guidelines) for details. + ## Terms To maintain consistency through GitLab documentation, use these styles and terms. diff --git a/doc/development/documentation/styleguide/word_list.md b/doc/development/documentation/styleguide/word_list.md index 1976caefc8e..029c7389290 100644 --- a/doc/development/documentation/styleguide/word_list.md +++ b/doc/development/documentation/styleguide/word_list.md @@ -8,8 +8,12 @@ description: 'Writing styles, markup, formatting, and other standards for GitLab # Recommended word list To help ensure consistency in the documentation, the Technical Writing team -recommends these wording choices. The GitLab handbook also maintains a list of -[top misused terms](https://about.gitlab.com/handbook/communication/top-misused-terms/). +recommends these word choices. In addition: + +- The GitLab handbook contains a list of + [top misused terms](https://about.gitlab.com/handbook/communication/top-misused-terms/). +- The documentation [style guide](../styleguide#language) includes details + about language and capitalization. For guidance not on this page, we defer to these style guides: @@ -19,6 +23,10 @@ For guidance not on this page, we defer to these style guides: <!-- vale off --> <!-- markdownlint-disable --> +## `&` + +Do not use Latin abbreviations. Use **and** instead, unless you are documenting a UI element that uses an `&`. + ## `@mention` Try to avoid **`@mention`**. Say **mention** instead, and consider linking to the @@ -75,7 +83,7 @@ Instead of: ## Admin Area -Use title case **Admin Area** to refer to the area of the UI that you access when you select **Menu > Admin**. +Use title case **Admin Area** to refer to the area of the UI that you access when you select **Main menu > Admin**. This area of the UI says **Admin Area** at the top of the page and on the menu. ## agent @@ -139,6 +147,18 @@ Do not use **and so on**. Instead, be more specific. For details, see Use [**section**](#section) instead of **area**. The only exception is [the Admin Area](#admin-area). +## as + +Do not use **as** to mean **because**. + +Use: + +- Because none of the endpoints return an ID... + +Instead of: + +- As none of the endpoints return an ID... + ## associate Do not use **associate** when describing adding issues to epics, or users to issues, merge requests, @@ -265,6 +285,13 @@ Use title case for the GitLab Container Registry. Do not use **currently** 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)) +## default branch + +Use **default branch** to refer generically to the primary branch in the repository. +Users can set the default branch by using a UI setting. + +For examples that use the default branch, use `main` instead of [`master`](#master). + ## Dependency Proxy Use title case for the GitLab Dependency Proxy. @@ -394,7 +421,7 @@ Information in FAQs belongs with other similar information, under an easily sear ## field -Use **box** instead of **field** or **text box**. +Use **text box** instead of **field** or **box**. Use: @@ -407,7 +434,7 @@ Instead of: 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 top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > CI/CD**. 1. Expand **General pipelines**. 1. Complete the fields. @@ -604,6 +631,10 @@ Instead of: - Buy a license. - Purchase a license. +## limitations + +Do not use **limitations**. Use **known issues** instead. + ## log in, log on Do not use **log in** or **log on**. Use [sign in](#sign-in) instead. If the user interface has **Log in**, you can use it. @@ -644,7 +675,8 @@ Do not use **manpower**. Use words like **workforce** or **GitLab team members** ## master -Do not use **master**. Options are **primary** or **main**. ([Vale](../testing.md#vale) rule: [`InclusionCultural.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionCultural.yml)) +Do not use `master`. Use `main` when you need a sample [default branch name](#default-branch). +([Vale](../testing.md#vale) rule: [`InclusionCultural.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionCultural.yml)) ## may, might diff --git a/doc/development/documentation/testing.md b/doc/development/documentation/testing.md index 428a57a11fb..59a078bdec0 100644 --- a/doc/development/documentation/testing.md +++ b/doc/development/documentation/testing.md @@ -190,7 +190,7 @@ To update the linting images: 1. In `gitlab-docs`, open a merge request to update `.gitlab-ci.yml` to use the new tooling version. ([Example MR](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/2571)) -1. When merged, start a `Build docs.gitlab.com every 4 hours` [scheduled pipeline](https://gitlab.com/gitlab-org/gitlab-docs/-/pipeline_schedules). +1. When merged, start a `Build docs.gitlab.com every hour` [scheduled pipeline](https://gitlab.com/gitlab-org/gitlab-docs/-/pipeline_schedules). 1. Go the pipeline you started, and manually run the relevant build-images job, for example, `image:docs-lint-markdown`. 1. In the job output, get the name of the new image. diff --git a/doc/development/documentation/topic_types/concept.md b/doc/development/documentation/topic_types/concept.md new file mode 100644 index 00000000000..a20bb93a97f --- /dev/null +++ b/doc/development/documentation/topic_types/concept.md @@ -0,0 +1,46 @@ +--- +stage: none +group: Style Guide +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Concept topic type + +A concept introduces a single feature or concept. + +A concept should answer the questions: + +- What is this? +- Why would I use it? + +Think of everything someone might want to know if they've never heard of this concept before. + +Don't tell them **how** to do this thing. Tell them **what it is**. + +If you start describing another concept, start a new concept and link to it. + +Concepts should be in this format: + +```markdown +# Title (a noun, like "Widgets") + +A paragraph that explains what this thing is. + +Another paragraph that explains what this thing is. + +Remember, if you start to describe about another concept, stop yourself. +Each concept should be about one concept only. +``` + +## Concept headings + +For the heading text, use a noun. For example, `Widgets` or `GDK dependency management`. + +If a noun is ambiguous, you can add a gerund. For example, `Documenting versions` instead of `Versions`. + +Avoid these heading titles: + +- `Overview` or `Introduction`. Instead, use a more specific + noun or phrase that someone would search for. +- `Use cases`. Instead, incorporate the information as part of the concept. +- `How it works`. Instead, use a noun followed by `workflow`. For example, `Merge request workflow`. diff --git a/doc/development/documentation/topic_types/index.md b/doc/development/documentation/topic_types/index.md new file mode 100644 index 00000000000..af3e66fe87a --- /dev/null +++ b/doc/development/documentation/topic_types/index.md @@ -0,0 +1,130 @@ +--- +stage: none +group: Style Guide +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# 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: + +- [Concept](concept.md) +- [Task](task.md) +- [Reference](reference.md) +- [Troubleshooting](troubleshooting.md) + +The tech writing team sometimes uses the acronym `CTRT` to refer to our topic types. +The acronym refers to the first letter of each topic type. + +In general, each page in the GitLab documentation contains multiple topics. +Each topic on a page should be recognizable as a specific topic type. + +## Other topic types + +In addition to the four primary topic types, we have a few other types. + +### Related topics + +If inline links are not sufficient, you can create a topic called **Related topics** +and include an unordered 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). +``` + +### Tutorials + +A tutorial is page that contains an end-to-end walkthrough of a complex workflow or scenario. +In general, you might consider using a tutorial when: + +- The workflow requires a number of sequential steps where each step consists + of sub-steps. +- The steps cover a variety of GitLab features or third-party tools. + +Tutorials are learning aids that complement our core documentation. +They do not introduce new features. +Always use the primary [topic types](#documentation-topic-types-ctrt) to document new features. + +Tutorials should be in this format: + +```markdown +# Title (starts with "Tutorial:" followed by an active verb, like "Tutorial: Create a website") + +A paragraph that explains what the tutorial does, and the expected outcome. + +To create a website: + +1. [Do the first task](#do-the-first-task) +1. [Do the second task](#do-the-second-task) + +Prerequisites (optional): + +- Thing 1 +- Thing 2 +- Thing 3 + +## Do the first task + +To do step 1: + +1. First step. +1. Another step. +1. Another step. + +## Do the second task + +Before you begin, make sure you have [done the first task](#do-the-first-task). + +To do step 2: + +1. First step. +1. Another step. +1. Another step. +``` + +### Get started + +A get started page is a set of steps to help a user get set up +quickly to use a single GitLab feature or tool. +It consists of more than one task. + +Get started pages should be in this format: + +```markdown +# Title ("Get started with <feature>") + +Complete the following steps to ... . + +1. First step. +1. Another step. +1. Another step. + +If you need to add more than one task, +consider using subsections for each distinct task. +``` + +In the left nav, use `Get started` as the text. On the page itself, spell out +the full name. For example, `Get started with application security`. + +### Topics and resources + +Some pages are solely a list of links to other documentation. + +We do not encourage this page type. Lists of links can get out-of-date quickly +and offer little value to users, who prefer to search to find information. + +## Heading text guidelines + +In general, for heading text: + +- Be clear and direct. Make every word count. +- Use articles and prepositions. +- Follow [capitalization](../styleguide/index.md#capitalization) guidelines. +- Do not repeat text from earlier headings. For example, if the page is about merge requests, + instead of `Troubleshooting merge requests`, use only `Troubleshooting`. + +See also [guidelines for headings in Markdown](../styleguide/index.md#headings-in-markdown). diff --git a/doc/development/documentation/topic_types/reference.md b/doc/development/documentation/topic_types/reference.md new file mode 100644 index 00000000000..42f4f5f6f94 --- /dev/null +++ b/doc/development/documentation/topic_types/reference.md @@ -0,0 +1,32 @@ +--- +stage: none +group: Style Guide +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Reference topic type + +Reference information should be in an easily-scannable format, +like a table or list. It's similar to a dictionary or encyclopedia entry. + +```markdown +# Title (a noun, like "Pipeline settings" or "Administrator options") + +Introductory sentence. + +| Setting | Description | +|---------|-------------| +| **Name** | Descriptive sentence about the setting. | +``` + +## Reference headings + +Reference headings are usually nouns. + +Avoid these heading titles: + +- `Important notes`. Instead, incorporate this information + closer to where it belongs. For example, this information might be a prerequisite + for a task, or information about a concept. +- `Limitations`. Instead, move the content near other similar information. + If you must, you can use the title `Known issues`. diff --git a/doc/development/documentation/topic_types/task.md b/doc/development/documentation/topic_types/task.md new file mode 100644 index 00000000000..3488cb90cf9 --- /dev/null +++ b/doc/development/documentation/topic_types/task.md @@ -0,0 +1,65 @@ +--- +stage: none +group: Style Guide +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Task topic type + +A task gives instructions for how to complete a procedure. + +Tasks should be in this format: + +```markdown +# Title (starts with an active verb, like "Create a widget" or "Delete a widget") + +Do this task when you want to... + +Prerequisites (optional): + +- Thing 1 +- Thing 2 +- Thing 3 + +To do this task: + +1. Location then action. (Go to this menu, then select this item.) +1. Another step. +1. Another step. + +Task result (optional). Next steps (optional). +``` + +Here is an example. + +```markdown +# Create an issue + +Create an issue when you want to track bugs or future work. + +Prerequisites: + +- You must have at least the Developer role for the project. + +To create an issue: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Issues > List**. +1. In the top right corner, select **New issue**. +1. Complete the fields. (If you have reference content that lists each field, link to it here.) +1. Select **Create issue**. + +The issue is created. You can view it by going to **Issues > List**. +``` + +## Task headings + +For the heading text, use the structure `active verb` + `noun`. +For example, `Create an issue`. + +If you have several tasks on a page that share prerequisites, you can use the title +`Prerequisites` and link to it. + +## Related topics + +- [View the format for writing task steps](../styleguide/index.md#navigation). diff --git a/doc/development/documentation/topic_types/troubleshooting.md b/doc/development/documentation/topic_types/troubleshooting.md new file mode 100644 index 00000000000..35187bd892e --- /dev/null +++ b/doc/development/documentation/topic_types/troubleshooting.md @@ -0,0 +1,56 @@ +--- +stage: none +group: Style Guide +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Troubleshooting topic type + +Troubleshooting topics should be the last topics on a page. + +If a page has more than five troubleshooting topics, put the content on a separate page that has troubleshooting information exclusively. Name the page `Troubleshooting <feature>` +and in the left nav, use the word `Troubleshoot` only. + +Troubleshooting can be one of three types. + +## An introductory topic + +This topic introduces the troubleshooting section of a page. +For example: + +```markdown +## Troubleshooting + +When working with <x feature>, you might encounter the following issues. +``` + +## Troubleshooting task + +The title should be similar to a [standard task](task.md). +For example, "Run debug tools" or "Verify syntax." + +## Troubleshooting reference + +This topic includes the error message. For example: + +```markdown +### The error message or a description of it + +You might get an error that states <error message>. + +This issue occurs when... + +The workaround is... +``` + +If multiple causes or workarounds exist, consider putting them into a table format. +If you use the exact error message, surround it in backticks so it's styled as code. + +## Troubleshooting headings + +For the heading of a **Troubleshooting reference** topic: + +- Consider including at least a partial error message. +- Use fewer than 70 characters. + +If you do not put the full error in the title, include it in the body text. diff --git a/doc/development/documentation/versions.md b/doc/development/documentation/versions.md index 3679c731a77..85733603cfe 100644 --- a/doc/development/documentation/versions.md +++ b/doc/development/documentation/versions.md @@ -69,6 +69,11 @@ If a feature is moved to another subscription tier, use `moved`: > - [Moved](<link-to-issue>) from GitLab Premium to GitLab Free in 12.0. ``` +#### Features introduced behind feature flags + +When features are introduced behind feature flags, you must add details about the feature flag to the documentation. +For more information, see [Document features deployed behind feature flags](feature_flags.md). + ### Inline version text If you're adding content to an existing topic, you can add version information @@ -205,7 +210,7 @@ You can say that we plan to remove a feature. ### Legal disclaimer for future features -If you **must** write about features we have not yet delivered, put this exact disclaimer near the content it applies to. +If you **must** write about features we have not yet delivered, put this exact disclaimer about forward-looking statements near the content it applies to. ```markdown DISCLAIMER: @@ -227,6 +232,6 @@ As with all projects, the items mentioned on this page are subject to change or The development, release, and timing of any products, features, or functionality remain at the sole discretion of GitLab Inc. -If all of the content on the page is not available, use the disclaimer once at the top of the page. +If all of the content on the page is not available, use the disclaimer about forward-looking statements once at the top of the page. If the content in a topic is not ready, use the disclaimer in the topic. |