diff options
Diffstat (limited to 'doc/development/documentation')
| -rw-r--r-- | doc/development/documentation/alpha_beta.md | 11 | ||||
| -rw-r--r-- | doc/development/documentation/experiment_beta.md | 2 | ||||
| -rw-r--r-- | doc/development/documentation/feature_flags.md | 2 | ||||
| -rw-r--r-- | doc/development/documentation/metadata.md | 39 | ||||
| -rw-r--r-- | doc/development/documentation/site_architecture/global_nav.md | 64 | ||||
| -rw-r--r-- | doc/development/documentation/styleguide/index.md | 69 | ||||
| -rw-r--r-- | doc/development/documentation/styleguide/word_list.md | 43 | ||||
| -rw-r--r-- | doc/development/documentation/testing.md | 30 | ||||
| -rw-r--r-- | doc/development/documentation/topic_types/troubleshooting.md | 2 |
9 files changed, 166 insertions, 96 deletions
diff --git a/doc/development/documentation/alpha_beta.md b/doc/development/documentation/alpha_beta.md deleted file mode 100644 index 4579c57b448..00000000000 --- a/doc/development/documentation/alpha_beta.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'experiment_beta.md' -remove_date: '2023-11-29' ---- - -This document was moved to [another location](experiment_beta.md). - -<!-- This redirect file can be deleted after <2023-11-29>. --> -<!-- 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 --> diff --git a/doc/development/documentation/experiment_beta.md b/doc/development/documentation/experiment_beta.md index 85f6dc38621..96e8d6fb638 100644 --- a/doc/development/documentation/experiment_beta.md +++ b/doc/development/documentation/experiment_beta.md @@ -32,7 +32,7 @@ On self-managed GitLab, by default this feature is not available. To make it available, an administrator can enable the feature flag named `example_flag`. On GitLab.com, this feature is not available. This feature is not ready for production use. -Use this great new feature when you need to do this new thing. +Use this new feature when you need to do this new thing. This feature is an [Experiment](<link_to>/policy/experiment-beta-support.md). To join the list of users testing this feature, do this thing. If you find a bug, diff --git a/doc/development/documentation/feature_flags.md b/doc/development/documentation/feature_flags.md index 617691e8628..637b2d163e7 100644 --- a/doc/development/documentation/feature_flags.md +++ b/doc/development/documentation/feature_flags.md @@ -17,7 +17,7 @@ When the state of a feature flag changes, the developer who made the change Every feature introduced to the codebase, even if it's behind a disabled feature flag, must be documented. For more information, see -[the discussion that led to this decision](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/47917#note_459984428). [Experiment or Beta](../../policy/experiment-beta-support.md) features are usually behind a feature flag, and must also be documented. For more information, see [Document Experiment or Beta features](alpha_beta.md). +[the discussion that led to this decision](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/47917#note_459984428). [Experiment or Beta](../../policy/experiment-beta-support.md) features are usually behind a feature flag, and must also be documented. For more information, see [Document Experiment or Beta features](experiment_beta.md). When the feature is [implemented in multiple merge requests](../feature_flags/index.md#feature-flags-in-gitlab-development), discuss the plan with your technical writer. diff --git a/doc/development/documentation/metadata.md b/doc/development/documentation/metadata.md index 4e80ea154b3..e6eff56d66d 100644 --- a/doc/development/documentation/metadata.md +++ b/doc/development/documentation/metadata.md @@ -32,11 +32,48 @@ To populate the metadata, include this information: - `info`: How to find the Technical Writer associated with the page's stage and group. +### Exceptions + +Documents in the `/development` directory get this metadata: + +```yaml +--- +stage: Example Stage +group: Example Group +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. +--- +``` + +Documents in the `/solutions` directory get this metadata: + +```yaml +--- +stage: Solutions Architecture +group: Solutions Architecture +info: This page is owned by the Solutions Architecture team. +--- +``` + +## Description metadata + +The `description` tag: + +- Is used to populate text on the docs home page. +- Is shown in social media previews. +- Can be used in search result snippets. + +For the top-level pages, like **Use GitLab** and one level underneath, +the descriptions are lists of nouns. For example, for **Set up your organization**, +the description is `Users, groups, namespaces, SSH keys.` + +For other pages, descriptions are not actively maintained. However, if you want to add one, +use 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 tips. + ## Additional metadata 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). diff --git a/doc/development/documentation/site_architecture/global_nav.md b/doc/development/documentation/site_architecture/global_nav.md index 0dfe538cfbd..be10688766f 100644 --- a/doc/development/documentation/site_architecture/global_nav.md +++ b/doc/development/documentation/site_architecture/global_nav.md @@ -26,6 +26,11 @@ For example: While some older sections of the nav are alphabetical, the nav should primarily be workflow-based. +Without a navigation entry: + +- The navigation closes when the page is opened, and the reader loses their place. +- The page isn't visible in a group with other pages. + ## Choose the right words for your navigation entry Before you add an item to the left nav, choose the parts of speech you want to use. @@ -41,35 +46,14 @@ as helpful as **Get started with runners**. ## Add a navigation entry -To add a topic to the global nav, edit -[`navigation.yaml`](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/content/_data/navigation.yaml) -and add your item. - -Without a navigation entry: - -- The navigation closes when the page is opened, and the reader loses their place. -- The page isn't visible in a group with other pages. - -### Pages you don't need to add - -Exclude these pages from the global nav: - -- Legal notices. -- Pages in the `architecture/blueprints` directory. -- Pages in the `user/application_security/dast/checks/` directory. - -The following pages should probably be in the global nav, but the technical writers -do not actively work to add them: - -- Pages in the `/development` directory. -- Pages authored by the support team, which are under the `doc/administration/troubleshooting` directory. +**Do not** add items to the global nav without +the consent of one of the technical writers. -Sometimes pages for deprecated features are not in the global nav, depending on how long ago the feature was deprecated. +To add a topic to the global navigation: -All other pages should be in the global nav. - -The technical writing team runs a report to determine which pages are not in the nav. -The team reviews this list each month. +1. In the [`navigation.yaml`](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/content/_data/navigation.yaml) + file, add the item. +1. Assign the MR to a technical writer for review and merge. ### Where to add @@ -110,7 +94,28 @@ mechanics of what is required is [documented below](#data-file) but, in principl substitution for **Continuous Integration**. - Navigation links must follow the rules documented in the [data file](#data-file). -## How it works +### Pages you don't need to add + +Exclude these pages from the global nav: + +- Legal notices. +- Pages in the `architecture/blueprints` directory. +- Pages in the `user/application_security/dast/checks/` directory. + +The following pages should probably be in the global nav, but the technical writers +do not actively work to add them: + +- Pages in the `/development` directory. +- Pages authored by the support team, which are under the `doc/administration/troubleshooting` directory. + +Sometimes pages for deprecated features are not in the global nav, depending on how long ago the feature was deprecated. + +All other pages should be in the global nav. + +The technical writing team runs a report to determine which pages are not in the nav. +The team reviews this list each month. + +## Navigation structure The global nav has five levels: @@ -122,9 +127,6 @@ The global nav has five levels: You can view this structure in [the `navigation.yml` file](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/content/_data/navigation.yaml). -**Do not** [add items](#add-a-navigation-entry) to the global nav without -the consent of one of the technical writers. - ## Composition The global nav is built from two files: diff --git a/doc/development/documentation/styleguide/index.md b/doc/development/documentation/styleguide/index.md index 26660d2eba1..a18b376a1cc 100644 --- a/doc/development/documentation/styleguide/index.md +++ b/doc/development/documentation/styleguide/index.md @@ -243,7 +243,7 @@ by default. Capitalize names of: - GitLab [product tiers](https://about.gitlab.com/pricing/). For example, - GitLab Free and GitLab Ultimate. (Tested in [`BadgeCapitalization.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/BadgeCapitalization.yml).) + GitLab Free and GitLab Ultimate. - Third-party organizations, software, and products. For example, Prometheus, Kubernetes, Git, and The Linux Foundation. - Methods or methodologies. For example, Continuous Integration, @@ -351,10 +351,10 @@ For numbers in text, spell out zero through nine and use numbers for 10 and grea - [Write in Markdown](#markdown). - Insert an empty line for new paragraphs. - Insert an empty line between different markups (for example, after every - paragraph, header, list, and so on). Example: + paragraph, heading, list, and so on). Example: ```markdown - ## Header + ## Heading Paragraph. @@ -692,9 +692,9 @@ Markdown tables naturally fall out of alignment over time, but still render corr on `docs.gitlab.com`. The technical writing team can realign cells the next time the page is refactored. -### Table headings +### Table headers -Use sentence case for table headings. For example, `Keyword value` or `Project name`. +Use sentence case for table headers. For example, `Keyword value` or `Project name`. ### Feature tables @@ -1140,7 +1140,7 @@ When you take screenshots: Reduce the size of your browser window as much as possible to keep elements close together and reduce empty space. Try to keep the screenshot dimensions as small as possible. - **Review how the image renders on the page.** Preview the image locally or use the -review app in the merge request. Make sure the image isn't blurry or overwhelming. + review app in the merge request. Make sure the image isn't blurry or overwhelming. - **Be consistent.** Coordinate screenshots with the other screenshots already on a documentation page for a consistent reading experience. Ensure your navigation theme is **Indigo** and the syntax highlighting theme is **Light**. These are the default preferences. @@ -1237,8 +1237,7 @@ and annoying for users. If you're describing a complicated interaction in the user interface and want to include a visual representation to help readers understand it, you can: -- Use a static image (screenshot) and if necessary, add callouts to emphasize an - an area of the screen. +- Use a static image (screenshot) and if necessary, add callouts to emphasize an area of the screen. - Create a short video of the interaction and link to it. ### Automatic screenshot generator @@ -1349,12 +1348,14 @@ Do not upload videos to the product repositories. [Link](#link-to-video) or ### Link to video -To link out to a video, include a YouTube icon so that readers can scan the page -for videos before reading: +To link to a video, include a YouTube icon so that readers can scan the page +for videos before reading. Include the video's publication date after the link, to help identify +videos that might be out-of-date. ```markdown <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an overview, see [Video Title](link-to-video). +<!-- Video published on YYYY-MM-DD --> ``` You can link any up-to-date video that's useful to the GitLab user. @@ -1384,6 +1385,8 @@ To embed a video: (`https://www.youtube-nocookie.com/embed/VIDEO-ID`), and paste it, replacing the content of the `src` field in the `iframe` tag. +1. Include the video's publication date below the link, to help identify + videos that might be out-of-date. ```html leave a blank line here @@ -1393,6 +1396,7 @@ leave a blank line here <figure class="video-container"> <iframe src="https://www.youtube-nocookie.com/embed/MqL6BMOySIQ" frameborder="0" allowfullscreen> </iframe> </figure> +<!-- Video published on YYYY-MM-DD --> leave a blank line here ``` @@ -1434,7 +1438,7 @@ NOTE: This is something to note. ``` -To display an alert box for multiple paragraphs, lists, or headers, use +To display an alert box for multiple paragraphs, lists, or headings, use [blockquotes](#blockquotes) instead. Alert boxes render only on the GitLab documentation site (<https://docs.gitlab.com>). @@ -1636,13 +1640,37 @@ When names change, it is more complicated to search or grep text that has line b Tier badges provide information about a feature and are displayed next to the topic title. -You should assign a tier badge: +#### When to add tier badges -- To all H1 topic titles, except the pages under `doc/development/*`. -- To topic titles that don't apply to the same tier as the H1. +Assign tier badges to: + +- All H1 topic titles, except the pages under `doc/development/*` and `doc/solutions/*`. +- Topic titles that don't apply to the same tier as the H1. The H1 tier badge should be the badge that applies to the lowest tier for the features on the page. +#### When not to add tier badges + +Do not assign tier badges: + +- When a feature does not have one obvious subscription tier or offering. + For example, if a feature applies to one tier for SaaS and a different tier for self-managed. + +In this case, do any or all of the following: + +- Use a `NOTE` in an alert box to describe the tiers. +- Add tier badges to other topic titles where this information makes more sense. +- Do not add tier badges to the H1. + +##### Pages that don't need a tier badge + +Some pages won't have a tier badge, because no obvious tier badge applies. For example: + +- Tutorials. +- Pages that compare features from different tiers. +- Pages in the `/development` folder. These pages are automatically assigned a `Contribute` badge. +- Pages in the `/solutions` folder. These pages are automatically assigned a `Solutions` badge. + #### Available product tier badges Tier badges should include two components, in this order: a subscription tier and an offering. @@ -1667,7 +1695,9 @@ You can also add a third component for the feature's status: For example, `**(FREE ALL EXPERIMENT)**`. -A tier or status can stand alone. An offering should always have a tier. +- A tier or status can stand alone. +- An offering should always have a tier. +- Do not add more than one offering, tier, or status. Multiples do not render properly in the documentation. #### Add a tier badge @@ -1697,15 +1727,6 @@ Do not add tier badges inline with other text, except for [API attributes](../re The single source of truth for a feature should be the topic where the functionality is described. -##### Pages that don't need a tier badge - -Some pages won't have a tier badge, because no obvious tier badge applies. For example: - -- Tutorials. -- Pages that compare features from different tiers. -- Pages in the `/development` folder. These pages are automatically assigned a `Contribute` badge. -- Pages in the `/solutions` folder. These pages are automatically assigned a `Solutions` badge. - ##### Administrator documentation tier badges Topics that are only for instance administrators should be badged `<TIER> SELF`. Instance diff --git a/doc/development/documentation/styleguide/word_list.md b/doc/development/documentation/styleguide/word_list.md index 9d0d59e27c5..fed295b8ec9 100644 --- a/doc/development/documentation/styleguide/word_list.md +++ b/doc/development/documentation/styleguide/word_list.md @@ -130,6 +130,10 @@ The token generated when you create an agent for Kubernetes. Use **agent access Use **AI**. Do not spell out **artificial intelligence**. +## AI-powered DevSecOps platform + +If preceded by GitLab, capitalize **Platform**. For example, the GitLab AI-powered DevSecOps Platform. + ## air gap, air-gapped Use **offline environment** to describe installations that have physical barriers or security policies that prevent or limit internet access. Do not use **air gap**, **air gapped**, or **air-gapped**. For example: @@ -239,6 +243,22 @@ Use **text box** to refer to the UI field. Do not use **field** or **box**. For - In the **Variable name** text box, enter a value. +## branch + +Use **branch** by itself to describe a branch. For specific branches, use these terms only: + +- **default branch**: The primary branch in the repository. Users can use the UI to set the default + branch. For examples that use the default branch, use `main` instead of [`master`](#master). +- **source branch**: The branch you're merging from. +- **target branch**: The branch you're merging to. +- **current branch**: The branch you have checked out. + This branch might be the default branch, a branch you've created, a source branch, or some other branch. + +Do not use the terms **feature branch** or **merge request branch**. Be as specific as possible. For example: + +- The branch you have checked out... +- The branch you added commits to... + ## bullet Don't refer to individual items in an ordered or unordered list as **bullets**. Use **list item** instead. If you need to be less ambiguous, you can use: @@ -428,13 +448,6 @@ Instead of: - Data are collected. - The data show a performance increase. -## 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). - ## delete Use **delete** when an object is completely deleted. **Delete** is the opposite of **create**. @@ -464,6 +477,10 @@ When writing about the Developer role: Do not use **Developer permissions**. A user who is assigned the Developer role has a set of associated permissions. +## DevSecOps platform + +If preceded by GitLab, capitalize **Platform**. For example, the GitLab DevSecOps Platform. + ## dialog Use **dialog** rather than any of these alternatives: @@ -661,6 +678,10 @@ Instead of: - Use the merge request feature to incorporate changes into the target branch. +## feature branch + +Do not use **feature branch**. See [branch](#branch). + ## field Use **text box** instead of **field** or **box**. @@ -1083,7 +1104,7 @@ Do not use **manpower**. Use words like **workforce** or **GitLab team members** ## master -Do not use `master`. Use `main` when you need a sample [default branch name](#default-branch). +Do not use **master**. Use **main** when you need a sample [default branch name](#branch). ([Vale](../testing.md#vale) rule: [`InclusionCultural.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionCultural.yml)) ## may, might @@ -1115,6 +1136,10 @@ For **MB** and **GB**, follow the [Microsoft guidance](https://learn.microsoft.c When you add a [user account](#user-account) to a group or project, the user account becomes a **member**. +## merge request branch + +Do not use **merge request branch**. See [branch](#branch). + ## merge requests Use lowercase for **merge requests**. If you use **MR** as the acronym, spell it out on first use. @@ -1570,7 +1595,7 @@ Searching is different from [filtering](#filter). When referring to the subscription billing model: - For GitLab SaaS, use **seats**. Customers purchase seats. Users occupy seats when they are invited -to a group, with some [exceptions](../../../subscriptions/gitlab_com/index.md#how-seat-usage-is-determined). + to a group, with some [exceptions](../../../subscriptions/gitlab_com/index.md#how-seat-usage-is-determined). - For GitLab self-managed, use **users**. Customers purchase subscriptions for a specified number of **users**. ## section diff --git a/doc/development/documentation/testing.md b/doc/development/documentation/testing.md index 62df2395fbb..8a38b0ed0e4 100644 --- a/doc/development/documentation/testing.md +++ b/doc/development/documentation/testing.md @@ -492,6 +492,7 @@ command line. To configure markdownlint in your editor, install one of the following as appropriate: +- Visual Studio Code [`DavidAnson.vscode-markdownlint` extension](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint). - Sublime Text [`SublimeLinter-contrib-markdownlint` package](https://packagecontrol.io/packages/SublimeLinter-contrib-markdownlint). This package uses `markdownlint-cli` by default, but can be configured to use `markdownlint-cli2` with this SublimeLinter configuration: @@ -502,11 +503,20 @@ To configure markdownlint in your editor, install one of the following as approp } ``` -- Visual Studio Code [`DavidAnson.vscode-markdownlint` extension](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint). - Vim [ALE plugin](https://github.com/dense-analysis/ale). +- Emacs [Flycheck extension](https://github.com/flycheck/flycheck). `Flycheck` supports + `markdownlint-cli` out of the box, but you must add a `.dir-locals.el` file to + point it to the `.markdownlint.yml` at the base of the project directory: + + ```lisp + ;; Place this code in a file called `.dir-locals.el` at the root of the gitlab project. + ((markdown-mode . ((flycheck-markdown-markdownlint-cli-config . ".markdownlint.yml")))) + ``` To configure Vale in your editor, install one of the following as appropriate: +- Visual Studio Code [`ChrisChinchilla.vale-vscode` extension](https://marketplace.visualstudio.com/items?itemName=ChrisChinchilla.vale-vscode). + You can configure the plugin to [display only a subset of alerts](#show-subset-of-vale-alerts). - Sublime Text [`SublimeLinter-vale` package](https://packagecontrol.io/packages/SublimeLinter-vale). To have Vale suggestions appears as blue instead of red (which is how errors appear), add `vale` configuration to your [SublimeLinter](http://sublimelinter.readthedocs.org) configuration: @@ -522,26 +532,12 @@ To configure Vale in your editor, install one of the following as appropriate: ``` - [LSP for Sublime Text](https://lsp.sublimetext.io) package [`LSP-vale-ls`](https://packagecontrol.io/packages/LSP-vale-ls). -- Visual Studio Code [`ChrisChinchilla.vale-vscode` extension](https://marketplace.visualstudio.com/items?itemName=ChrisChinchilla.vale-vscode). - 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: - - - `Flycheck` supports `markdownlint-cli` out of the box, but you must point it - to the `.markdownlint.yml` at the base of the project directory. A `.dir-locals.el` - file can accomplish this: - - ```lisp - ;; Place this code in a file called `.dir-locals.el` at the root of the gitlab project. - ((markdown-mode . ((flycheck-markdown-markdownlint-cli-config . ".markdownlint.yml")))) - - ``` - - - A minimal configuration for Flycheck to work with Vale could look like this: +- Emacs [Flycheck extension](https://github.com/flycheck/flycheck). A minimal configuration + for Flycheck to work with Vale could look like: ```lisp (flycheck-define-checker vale diff --git a/doc/development/documentation/topic_types/troubleshooting.md b/doc/development/documentation/topic_types/troubleshooting.md index aee5bd1377c..f970b58e4fc 100644 --- a/doc/development/documentation/topic_types/troubleshooting.md +++ b/doc/development/documentation/topic_types/troubleshooting.md @@ -64,7 +64,7 @@ The workaround is... If multiple causes or solutions 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. -For more guidance on solution types, see [workaround](../../documentation/styleguide/word_list.md#workaround) and [resolution, resolve](../../documentation/styleguide/word_list.md#resolution-resolve). +For more guidance on solution types, see [workaround](../../documentation/styleguide/word_list.md#workaround) and [resolution, resolve](../../documentation/styleguide/word_list.md#resolution-resolve). ## Troubleshooting topic titles |