diff options
Diffstat (limited to 'doc/development/documentation')
11 files changed, 98 insertions, 25 deletions
diff --git a/doc/development/documentation/graphql_styleguide.md b/doc/development/documentation/graphql_styleguide.md index 79fcfc7e3f0..3c96dd06b25 100644 --- a/doc/development/documentation/graphql_styleguide.md +++ b/doc/development/documentation/graphql_styleguide.md @@ -1,7 +1,7 @@ --- type: reference, dev stage: none -group: Development +group: unassigned info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines" description: "Writing styles, markup, formatting, and other standards for GraphQL API's GitLab Documentation." --- diff --git a/doc/development/documentation/styleguide/index.md b/doc/development/documentation/styleguide/index.md index 0fa5819acae..c3df15f1890 100644 --- a/doc/development/documentation/styleguide/index.md +++ b/doc/development/documentation/styleguide/index.md @@ -177,9 +177,14 @@ To populate the metadata, include this information: ### Additional metadata -Each page can have additional, optional metadata (set in the -[default.html](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/fc3577921343173d589dfa43d837b4307e4e620f/layouts/default.html#L30-52) -Nanoc layout), which is displayed at the top of the page if defined. +The following metadata is optional and is not actively maintained. + +- `description`: A short description of what the page is about. See the Google [Best practices for creating quality meta descriptions](https://developers.google.com/search/docs/appearance/snippet#meta-descriptions) for writing tips. This content can be used in search result snippets and is shown in social media previews. +- `feedback`: Set to `false` to not include the "Help & Feedback" footer. +- `noindex`: Set to `false` to prevent the page from being indexed by search engines. +- `redirect_to`: Used to control redirects. For more information, see [Redirects in GitLab documentation](../redirects.md). +- `searchbar`: Set to `false` to not include the search bar in the page header. +- `toc`: Set to `false` to not include the "On this page" navigation. ### Deprecated metadata @@ -1435,7 +1440,7 @@ different mobile devices. > - The `<div class="video-fallback">` is a fallback necessary for `/help`, because the GitLab Markdown processor doesn't support iframes. It's hidden on the documentation site, but is displayed by `/help`. -> - The `www.youtube-nocookie.com` domain enables the [Privacy Enhanced Mode](https://support.google.com/youtube/answer/171780?hl=en#zippy=%2Cturn-on-privacy-enhanced-mode) of the YouTube embedded player. This mode allows users with resticted cookie preferences to view embedded videos. +> - The `www.youtube-nocookie.com` domain enables the [Privacy Enhanced Mode](https://support.google.com/youtube/answer/171780?hl=en#zippy=%2Cturn-on-privacy-enhanced-mode) of the YouTube embedded player. This mode allows users with restricted cookie preferences to view embedded videos. ## Alert boxes @@ -1980,3 +1985,44 @@ It renders as: ``` ::EndTabs + +### Changes for a version upgrade + +To document upgrade notes and changes, create a new page for each major version of GitLab. +For an example, see [GitLab 16 changes](../../../update/versions/gitlab_16_changes.md). +Use the following template to add information to the page. + +```markdown +# GitLab X changes **(FREE SELF)** + +This page contains upgrade information for minor and patch versions of GitLab X. Review these instructions for: + +- Your installation type. +- All versions between your current version and your target version. + +For more information about upgrading GitLab Helm Chart, see [the release notes for X.0](https://docs.gitlab.com/charts/releases/X_0.html). + +## X.Y.1 (add the latest version at the top of the page) + +- General upgrade notes and issues. +- ... + +### Linux package installations + +- Information specific to Linux package installations. +- ... + +### Self-compiled installations + +- Information specific to self-compiled installations. +- ... + +### Geo installations **(PREMIUM SELF)** + + - Information specific to Geo. + - ... + +## X.Y.0 + + ... +``` diff --git a/doc/development/documentation/styleguide/word_list.md b/doc/development/documentation/styleguide/word_list.md index 509cabbe631..ad2cbee974b 100644 --- a/doc/development/documentation/styleguide/word_list.md +++ b/doc/development/documentation/styleguide/word_list.md @@ -1,6 +1,6 @@ --- stage: none -group: Style Guide +group: Documentation Guidelines info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments description: 'Writing styles, markup, formatting, and other standards for GitLab Documentation.' --- @@ -208,6 +208,14 @@ Instead, use **assign**. For example: Use **authenticated user** instead of other variations, like **signed in user** or **logged in user**. +## before you begin + +Use **before you begin** when documenting the tasks that must be completed or the conditions that must be met before a user can complete a tutorial. Do not use **requirements** or **prerequisites**. + +For more information, see [the tutorial page type](../topic_types/tutorial.md). + +For task topic types, use [**prerequisites**](#prerequisites) instead. + ## below Try to avoid **below** when referring to an example or table in a documentation page. If required, use **following** instead. For example: @@ -666,6 +674,10 @@ Do not make **GitLab** possessive (GitLab's). This guidance follows [GitLab Trad ## GitLab Dedicated +Use **GitLab Dedicated** to refer to the product offering. It refers to a GitLab instance that's hosted and managed by GitLab for customers. + +GitLab Dedicated can be referred to as a single-tenant SaaS service. + Do not use **Dedicated** by itself. Always use **GitLab Dedicated**. ## GitLab Duo @@ -732,16 +744,16 @@ See also: ## GitLab SaaS -**GitLab SaaS** refers to the product license that provides access to GitLab.com. It does not refer to the -GitLab instance managed by GitLab itself. +Use **GitLab SaaS** to refer to the product offering. +It does not refer to the GitLab instance, which is [GitLab.com](#gitlabcom). ## GitLab self-managed -Use **GitLab self-managed** to refer to the product license for GitLab instances managed by customers themselves. +Use **GitLab self-managed** to refer to the product offering. It refers to a GitLab instance managed by customers themselves. ## GitLab.com -**GitLab.com** refers to the GitLab instance managed by GitLab itself. +Use **GitLab.com** to refer to the URL. GitLab.com is the instance that's managed by GitLab. ## guide @@ -1124,6 +1136,16 @@ Instead of: - Note that you can change the settings. +## offerings + +The current product offerings are: + +- [GitLab SaaS](#gitlab-saas) +- [GitLab self-managed](#gitlab-self-managed) +- [GitLab Dedicated](#gitlab-dedicated) + +The [tier badges](index.md#available-product-tier-badges) reflect these offerings. + ## older Do not use **older** when talking about version numbers. @@ -1253,10 +1275,12 @@ in the context of other subscription tiers, follow [the subscription tier](#subs ## prerequisites -Use **prerequisites** when documenting the steps before a task. Do not use **requirements**. +Use **prerequisites** when documenting the tasks that must be completed or the conditions that must be met before a user can complete a task. Do not use **requirements**. For more information, see [the task topic type](../topic_types/task.md). +For tutorial page types, use [**before you begin**](#before-you-begin) instead. + ## press Use **press** when talking about keyboard keys. For example: @@ -1321,9 +1345,12 @@ Use title case for **Repository Mirroring**. ## requirements -Use **prerequisites** when documenting the steps before a task. Do not use **requirements**. +When documenting the tasks that must be completed or the conditions that must be met before a user can complete the steps: -For more information, see [the task topic type](../topic_types/task.md). +- Use **prerequisites** for tasks. For more information, see [the task topic type](../topic_types/task.md). +- Use **before you begin** for tutorials. For more information, see [the tutorial page type](../topic_types/tutorial.md). + +Do not use **requirements**. ## respectively diff --git a/doc/development/documentation/testing.md b/doc/development/documentation/testing.md index c0f1d0028f9..414c2bede7b 100644 --- a/doc/development/documentation/testing.md +++ b/doc/development/documentation/testing.md @@ -102,7 +102,7 @@ The output should be similar to: This requires you to either: - Have the [required lint tools installed](#local-linters) on your computer. -- A working Docker or containerd installation, to use an image with these tools pre-installed. +- A working Docker or `containerd` installation, to use an image with these tools pre-installed. ### Documentation link tests diff --git a/doc/development/documentation/topic_types/concept.md b/doc/development/documentation/topic_types/concept.md index c9aedf940a2..50220b9bebe 100644 --- a/doc/development/documentation/topic_types/concept.md +++ b/doc/development/documentation/topic_types/concept.md @@ -1,6 +1,6 @@ --- stage: none -group: Style Guide +group: Documentation Guidelines info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/development/documentation/topic_types/glossary.md b/doc/development/documentation/topic_types/glossary.md index 4985101a391..f6137953cb0 100644 --- a/doc/development/documentation/topic_types/glossary.md +++ b/doc/development/documentation/topic_types/glossary.md @@ -1,6 +1,6 @@ --- stage: none -group: Style Guide +group: Documentation Guidelines info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/development/documentation/topic_types/index.md b/doc/development/documentation/topic_types/index.md index 40039ca5b1a..10e7e3d2014 100644 --- a/doc/development/documentation/topic_types/index.md +++ b/doc/development/documentation/topic_types/index.md @@ -1,6 +1,6 @@ --- stage: none -group: Style Guide +group: Documentation Guidelines info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/development/documentation/topic_types/reference.md b/doc/development/documentation/topic_types/reference.md index 8bb89f4c210..ef2ca2f791d 100644 --- a/doc/development/documentation/topic_types/reference.md +++ b/doc/development/documentation/topic_types/reference.md @@ -1,6 +1,6 @@ --- stage: none -group: Style Guide +group: Documentation Guidelines info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/development/documentation/topic_types/task.md b/doc/development/documentation/topic_types/task.md index 7fb4201ac40..a6e4c01505d 100644 --- a/doc/development/documentation/topic_types/task.md +++ b/doc/development/documentation/topic_types/task.md @@ -1,6 +1,6 @@ --- stage: none -group: Style Guide +group: Documentation Guidelines info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/development/documentation/topic_types/troubleshooting.md b/doc/development/documentation/topic_types/troubleshooting.md index 4b23117acdb..a2fe6f8ca2d 100644 --- a/doc/development/documentation/topic_types/troubleshooting.md +++ b/doc/development/documentation/topic_types/troubleshooting.md @@ -1,6 +1,6 @@ --- stage: none -group: Style Guide +group: Documentation Guidelines info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/development/documentation/topic_types/tutorial.md b/doc/development/documentation/topic_types/tutorial.md index 2d57029b786..50976149cf8 100644 --- a/doc/development/documentation/topic_types/tutorial.md +++ b/doc/development/documentation/topic_types/tutorial.md @@ -1,6 +1,6 @@ --- stage: none -group: Style Guide +group: Documentation Guidelines info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -25,7 +25,7 @@ In general, you might consider using a tutorial when: ideal to duplicate content that is available elsewhere, it's worse to force the reader to leave the page to find what they need. -## Tutorial file name and location +## Tutorial filename and location For tutorial Markdown files, you can either: @@ -50,9 +50,9 @@ To create a website: 1. [Do the first task](#do-the-first-task) 1. [Do the second task](#do-the-second-task) -## Prerequisites +## Before you begin -This topic is optional. +This section is optional. - Thing 1 - Thing 2 @@ -85,7 +85,7 @@ An example of a tutorial that follows this format is Start the page title with `Tutorial:` followed by an active verb, like `Tutorial: Create a website`. In the left nav, use the full page title. Do not abbreviate it. -Put the text in quotes so the pipeline will pass. For example, +Put the text in quotes so the pipeline succeeds. For example, `"Tutorial: Make your first Git commit"`. On [the **Learn GitLab with tutorials** page](../../../tutorials/index.md), |