summaryrefslogtreecommitdiff
path: root/doc/development/documentation
diff options
context:
space:
mode:
Diffstat (limited to 'doc/development/documentation')
-rw-r--r--doc/development/documentation/feature_flags.md13
-rw-r--r--doc/development/documentation/restful_api_styleguide.md62
-rw-r--r--doc/development/documentation/site_architecture/index.md75
-rw-r--r--doc/development/documentation/structure.md4
-rw-r--r--doc/development/documentation/styleguide/index.md349
-rw-r--r--doc/development/documentation/styleguide/word_list.md74
-rw-r--r--doc/development/documentation/testing.md37
-rw-r--r--doc/development/documentation/versions.md232
-rw-r--r--doc/development/documentation/workflow.md2
9 files changed, 474 insertions, 374 deletions
diff --git a/doc/development/documentation/feature_flags.md b/doc/development/documentation/feature_flags.md
index fb58851e93f..c5ea1985fc7 100644
--- a/doc/development/documentation/feature_flags.md
+++ b/doc/development/documentation/feature_flags.md
@@ -45,7 +45,7 @@ You can combine entries if they happened in the same release:
## Use a note to describe the state of the feature flag
-Information about feature flags should be in a **Note** at the start of the topic (just below the version history).
+Information about feature flags should be in a `FLAG` note at the start of the topic (just below the version history).
The note has three parts, and follows this structure:
@@ -62,6 +62,7 @@ FLAG:
|--------------------------|---------------|
| Available | `On self-managed GitLab, by default this feature is available. To hide the feature, ask an administrator to [disable the feature flag](<path to>/administration/feature_flags.md) named <flag name>.` |
| Unavailable | `On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](<path to>/administration/feature_flags.md) named <flag name>.` |
+| Available to some users | `On self-managed GitLab, by default this feature is available to a subset of users. To show or hide the feature for all, ask an administrator to [change the status of the feature flag](<path to>/administration/feature_flags.md) named <flag name>.` |
| Available, per-group | `On self-managed GitLab, by default this feature is available. To hide the feature per group, ask an administrator to [disable the feature flag](<path to>/administration/feature_flags.md) named <flag name>.` |
| Unavailable, per-group | `On self-managed GitLab, by default this feature is not available. To make it available per group, ask an administrator to [enable the feature flag](<path to>/administration/feature_flags.md) named <flag name>.` |
| Available, per-project | `On self-managed GitLab, by default this feature is available. To hide the feature per project or for your entire instance, ask an administrator to [disable the feature flag](<path to>/administration/feature_flags.md) named <flag name>.` |
@@ -71,11 +72,11 @@ FLAG:
### GitLab.com availability information
-| If the feature is... | Use this text |
-|-------------------------------------|---------------|
-| Available | `On GitLab.com, this feature is available.` |
-| Available to GitLab.com admins only | `On GitLab.com, this feature is available but can be configured by GitLab.com administrators only.`
-| Unavailable | `On GitLab.com, this feature is not available.`|
+| If the feature is... | Use this text |
+|---------------------------------------------|---------------|
+| Available | `On GitLab.com, this feature is available.` |
+| Available to GitLab.com administrators only | `On GitLab.com, this feature is available but can be configured by GitLab.com administrators only.`
+| Unavailable | `On GitLab.com, this feature is not available.`|
### Optional information
diff --git a/doc/development/documentation/restful_api_styleguide.md b/doc/development/documentation/restful_api_styleguide.md
index 8a505ed84a8..0a24f9b67be 100644
--- a/doc/development/documentation/restful_api_styleguide.md
+++ b/doc/development/documentation/restful_api_styleguide.md
@@ -26,11 +26,12 @@ In the Markdown doc for a resource (AKA endpoint):
GET /projects/:id/repository/branches
```
-- Every method must have a detailed [description of the parameters](#method-description).
+- Every method must have a detailed [description of the attributes](#method-description).
- Every method must have a cURL example.
-- Every method must have a response body (in JSON format).
+- Every method must have a detailed [description of the response body](#response-body-description).
+- Every method must have a response body example (in JSON format).
- If an attribute is available only to higher level tiers than the other
- parameters, add the appropriate inline [tier badge](styleguide/index.md#product-tier-badges).
+ attributes, add the appropriate inline [tier badge](styleguide/index.md#product-tier-badges).
Put the badge in the **Attribute** column, like the
`**(<tier>)**` code in the following template.
@@ -59,6 +60,13 @@ Supported attributes:
| `attribute` | datatype | **{dotted-circle}** No | Detailed description. |
| `attribute` | datatype | **{dotted-circle}** No | Detailed description. |
+Response body attributes:
+
+| Attribute | Type | Description |
+|:-------------------------|:---------|:----------------------|
+| `attribute` | datatype | Detailed description. |
+| `attribute` **(<tier>)** | datatype | Detailed description. |
+
Example request:
```shell
@@ -75,7 +83,7 @@ Example response:
```
````
-Adjust the [version history note accordingly](styleguide/index.md#version-text-in-the-version-history)
+Adjust the [version history note accordingly](versions.md#add-a-version-history-item)
to describe the GitLab release that introduced the API call.
## Method description
@@ -86,23 +94,51 @@ always be in code blocks using backticks (`` ` ``).
Sort the table by required attributes first, then alphabetically.
```markdown
-| Attribute | Type | Required | Description |
-|:-----------------------------|:--------------|:-----------------------|:-----------------------------------------------------|
+| 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. |
+| `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`. |
```
Rendered example:
-| Attribute | Type | Required | Description |
-|:-----------------------------|:--------------|:-----------------------|:-----------------------------------------------------|
+| 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. |
+| `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`. |
For information about writing attribute descriptions, see the [GraphQL API description style guide](../api_graphql_styleguide.md#description-style-guide).
+## Response body description
+
+Use the following table headers to describe the response bodies. Attributes should
+always be in code blocks using backticks (`` ` ``).
+
+If the attribute is a complex type, like another object, represent sub-attributes
+with dots (`.`), like `project.name` or `projects[].name` in case of an array.
+
+Sort the table alphabetically.
+
+```markdown
+| Attribute | Type | Description |
+|:-----------------------------|:--------------|:------------------------------------------|
+| `assignee_ids` **(PREMIUM)** | integer array | IDs of the users to assign the issue to. |
+| `confidential` | boolean | Whether the issue is confidential or not. |
+| `title` | string | Title of the issue. |
+```
+
+Rendered example:
+
+| Attribute | Type | Description |
+|:-----------------------------|:--------------|:------------------------------------------|
+| `assignee_ids` **(PREMIUM)** | integer array | IDs of the users to assign the issue to. |
+| `confidential` | boolean | Whether the issue is confidential or not. |
+| `title` | string | Title of the issue. |
+
+For information about writing attribute descriptions, see the [GraphQL API description style guide](../api_graphql_styleguide.md#description-style-guide).
+
## cURL commands
- Use `https://gitlab.example.com/api/v4/` as an endpoint.
@@ -116,9 +152,9 @@ For information about writing attribute descriptions, see the [GraphQL API descr
| Methods | Description |
|:------------------------------------------------|:-------------------------------------------------------|
| `--header "PRIVATE-TOKEN: <your_access_token>"` | Use this method as is, whenever authentication needed. |
-| `--request POST` | Use this method when creating new objects |
-| `--request PUT` | Use this method when updating existing objects |
-| `--request DELETE` | Use this method when removing existing objects |
+| `--request POST` | Use this method when creating new objects. |
+| `--request PUT` | Use this method when updating existing objects. |
+| `--request DELETE` | Use this method when removing existing objects. |
## cURL Examples
diff --git a/doc/development/documentation/site_architecture/index.md b/doc/development/documentation/site_architecture/index.md
index bdda15e2064..3566ab82379 100644
--- a/doc/development/documentation/site_architecture/index.md
+++ b/doc/development/documentation/site_architecture/index.md
@@ -22,25 +22,29 @@ from where content is sourced, the `gitlab-docs` project, and the published outp
```mermaid
graph LR
- A[gitlab/doc]
- B[gitlab-runner/docs]
- C[omnibus-gitlab/doc]
- D[charts/doc]
- E[gitlab-docs]
- A --> E
- B --> E
- C --> E
- D --> E
- E -- Build pipeline --> F
- F[docs.gitlab.com]
- H[/ee/]
- I[/runner/]
- J[/omnibus/]
- K[/charts/]
- F --> H
- F --> I
- F --> J
- F --> K
+ A[gitlab-org/gitlab/doc]
+ B[gitlab-org/gitlab-runner/docs]
+ C[gitlab-org/omnibus-gitlab/doc]
+ D[gitlab-org/charts/gitlab/doc]
+ E[gitlab-org/cloud-native/gitlab-operator/doc]
+ Y[gitlab-org/gitlab-docs]
+ A --> Y
+ B --> Y
+ C --> Y
+ D --> Y
+ E --> Y
+ Y -- Build pipeline --> Z
+ Z[docs.gitlab.com]
+ M[//ee/]
+ N[//runner/]
+ O[//omnibus/]
+ P[//charts/]
+ Q[//operator/]
+ Z --> M
+ Z --> N
+ Z --> O
+ Z --> P
+ Z --> Q
```
GitLab docs content isn't kept in the `gitlab-docs` repository.
@@ -48,9 +52,10 @@ All documentation files are hosted in the respective repository of each
product, and all together are pulled to generate the docs website:
- [GitLab](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc)
-- [Omnibus GitLab](https://gitlab.com/gitlab-org/omnibus-gitlab/tree/master/doc)
+- [Omnibus GitLab](https://gitlab.com/gitlab-org/omnibus-gitlab/-/tree/master/doc)
- [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner/-/tree/main/docs)
-- [GitLab Chart](https://gitlab.com/charts/gitlab/tree/master/doc)
+- [GitLab Chart](https://gitlab.com/gitlab-org/charts/gitlab/-/tree/master/doc)
+- [GitLab Operator](https://gitlab.com/gitlab-org/cloud-native/gitlab-operator/-/tree/master/doc)
Learn more about [the docs folder structure](folder_structure.md).
@@ -231,31 +236,9 @@ If you don't specify `editor:`, the simple one is used by default.
## Algolia search engine
The docs site uses [Algolia DocSearch](https://community.algolia.com/docsearch/)
-for its search function. This is how it works:
-
-1. GitLab is a member of the [DocSearch program](https://community.algolia.com/docsearch/#join-docsearch-program),
- which is the free tier of [Algolia](https://www.algolia.com/).
-1. Algolia hosts a [DocSearch configuration](https://github.com/algolia/docsearch-configs/blob/master/configs/gitlab.json)
- for the GitLab docs site, and we've worked together to refine it.
-1. That [configuration](https://community.algolia.com/docsearch/config-file.html) is
- parsed by their [crawler](https://community.algolia.com/docsearch/crawler-overview.html)
- every 24h and [stores](https://community.algolia.com/docsearch/inside-the-engine.html)
- the [DocSearch index](https://community.algolia.com/docsearch/how-do-we-build-an-index.html)
- on [Algolia's servers](https://community.algolia.com/docsearch/faq.html#where-is-my-data-hosted%3F).
-1. On the docs side, we use a [DocSearch layout](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/layouts/docsearch.html) which
- is present on pretty much every page except <https://docs.gitlab.com/search/>,
- which uses its [own layout](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/layouts/instantsearch.html). In those layouts,
- there's a JavaScript snippet which initiates DocSearch by using an API key
- and an index name (`gitlab`) that are needed for Algolia to show the results.
-
-### Algolia notes for GitLab team members
-
-If you're a GitLab team member, find credentials for the Algolia dashboard
-in the shared [GitLab 1Password account](https://about.gitlab.com/handbook/security/#1password-for-teams).
-To receive weekly reports of the search usage, search the Google doc with
-title `Email, Slack, and GitLab Groups and Aliases`, search for `docsearch`,
-and add a comment with your email to be added to the alias that gets the weekly
-reports.
+for its search function.
+
+Learn more in <https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/doc/docsearch.md>.
## Monthly release process (versions)
diff --git a/doc/development/documentation/structure.md b/doc/development/documentation/structure.md
index 21368098f39..329fd279b99 100644
--- a/doc/development/documentation/structure.md
+++ b/doc/development/documentation/structure.md
@@ -237,7 +237,7 @@ consider using subsections for each distinct task.
### Related topics
If inline links are not sufficient, you can create a topic called **Related topics**
-and include a bulleted list of related topics. This topic should be above the Troubleshooting section.
+and include an unordered list of related topics. This topic should be above the Troubleshooting section.
```markdown
# Related topics
@@ -336,7 +336,7 @@ Consider the following guidelines when offering examples:
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 case(s) code block.
+- 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
diff --git a/doc/development/documentation/styleguide/index.md b/doc/development/documentation/styleguide/index.md
index 7bfc0320d02..c11d1422167 100644
--- a/doc/development/documentation/styleguide/index.md
+++ b/doc/development/documentation/styleguide/index.md
@@ -276,7 +276,6 @@ You can use these fake tokens as examples:
| Trigger token | `be20d8dcc028677c931e04f3871a9b` |
| Webhook secret token | `6XhDroRcYPM5by_h-HLY` |
| Health check token | `Tu7BgjR9qeZTEyRzGG2P` |
-| Request profile token | `7VgpS4Ax5utVD2esNstz` |
### Contractions
@@ -401,6 +400,39 @@ Backticks are more precise than quotes. For example, in this string:
It's not clear whether the user should include the period in the string.
+### Inline code
+
+Inline code style is applied inline with regular text. Use inline code style:
+
+- For filenames or fragments of configuration files. For example, `.gitlab-ci.yml`, `CODEOWNERS`, and `only: [main]`.
+- For HTTP methods (`HTTP POST`) and HTTP status codes, both full (`404 File Not Found`) and abbreviated (`404`).
+ For example: Send a `DELETE` request to delete the runner. Send a `POST` request to create one.
+
+To apply inline code style, wrap the text in a single backtick (`` ` ``). For example, `this is inline code style`.
+
+### Code blocks
+
+Code block style separates code text from regular text. Use code block style for commands run in the command-line
+interface. Code block style is easier to copy and paste in a user's terminal window.
+
+To apply code block style, wrap the text in triple backticks (three `` ` ``) and add a syntax highlighting hint. For
+example:
+
+````plaintext
+```plaintext
+This is codeblock style
+```
+````
+
+When using code block style:
+
+- Use quadruple backticks (four `` ` ``) to apply code block style when the code block you are styling has triple
+ backticks in it. For example, when illustrating code block style.
+- Add a blank line above and below code blocks.
+- Syntax highlight hints are required for code blocks. See the
+ [list of supported languages and lexers](https://github.com/rouge-ruby/rouge/wiki/List-of-supported-languages-and-lexers)
+ for available syntax highlighters. Use `plaintext` if no better hint is available.
+
## Lists
- Always start list items with a capital letter, unless they're parameters or
@@ -622,7 +654,10 @@ In the Markdown document:
For the heading text, **do**:
- Be clear and direct. Make every word count.
-- Use active verbs for tasks. For example, `Configure GDK` instead of `Configuring GDK`.
+- Use active, imperative verbs for [tasks](../structure.md#task). For example, `Create an issue`.
+- Use `ing` (gerund) verbs only when you need a topic that introduces tasks. For example, `Configuring GDK`.
+- Use nouns for [concepts](../structure.md#concept). For example, `GDK dependency management`. If a noun is
+ ambiguous, you can add a gerund. For example, `Documenting versions` instead of `Versions`.
- Talk about what the product does, realistically but from a positive perspective. Instead of
`Limitations`, move the content near other similar information. If you must, you can
use the title `Known issues`.
@@ -695,7 +730,6 @@ We include guidance for links in these categories:
for authoritative sources.
- When to use [links requiring permissions](#links-requiring-permissions).
- How to set up a [link to a video](#link-to-video).
-- How to [include links with version text](#where-to-put-version-text).
- How to [link to specific lines of code](#link-to-specific-lines-of-code)
### Basic link criteria
@@ -949,7 +983,7 @@ If you are documenting multiple fields and only one field needs explanation, do
1. Expand **Push rules**.
1. Complete the fields. **Branch name** must be a regular expression.
-To describe multiple fields, use bullets:
+To describe multiple fields, use unordered list items:
1. Expand **General pipelines**.
1. Complete the fields.
@@ -1166,80 +1200,6 @@ different mobile devices.
`/help`, because the GitLab Markdown processor doesn't support iframes. It's
hidden on the documentation site, but is displayed by `/help`.
-## Code blocks
-
-- Always wrap code added to a sentence in inline code blocks (`` ` ``).
- For example, `.gitlab-ci.yml`, `git add .`, `CODEOWNERS`, or `only: [main]`.
- File names, commands, entries, and anything that refers to code should be
- added to code blocks. To make things easier for the user, always add a full
- code block for things that can be useful to copy and paste, as they can do it
- with the button on code blocks.
-- HTTP methods (`HTTP POST`) and HTTP status codes, both full (`404 File Not Found`)
- and abbreviated (`404`), should be wrapped in inline code blocks when used in sentences.
- For example: Send a `DELETE` request to delete the runner. Send a `POST` request to create one.
-- Add a blank line above and below code blocks.
-- When providing a shell command and its output, prefix the shell command with `$`
- and leave a blank line between the command and the output.
-- When providing a command without output, don't prefix the shell command with `$`.
-- If you need to include triple backticks inside a code block, use four backticks
- for the code block fences instead of three.
-- For regular fenced code blocks, always use a highlighting class corresponding to
- the language for better readability. Examples:
-
- ````markdown
- ```ruby
- Ruby code
- ```
-
- ```javascript
- JavaScript code
- ```
-
- ```markdown
- [Markdown code example](example.md)
- ```
-
- ```plaintext
- Code or text for which no specific highlighting class is available.
- ```
- ````
-
-Syntax highlighting is required for fenced code blocks added to the GitLab
-documentation. Refer to this table for the most common language classes,
-or check the [complete list](https://github.com/rouge-ruby/rouge/wiki/List-of-supported-languages-and-lexers)
-of available language classes:
-
-| Preferred language tags | Language aliases and notes |
-|-------------------------|------------------------------------------------------------------------------|
-| `asciidoc` | |
-| `dockerfile` | Alias: `docker`. |
-| `elixir` | |
-| `erb` | |
-| `golang` | Alias: `go`. |
-| `graphql` | |
-| `haml` | |
-| `html` | |
-| `ini` | For some simple configuration files that are not in TOML format. |
-| `javascript` | Alias `js`. |
-| `json` | |
-| `markdown` | Alias: `md`. |
-| `mermaid` | |
-| `nginx` | |
-| `perl` | |
-| `php` | |
-| `plaintext` | Examples with no defined language, such as output from shell commands or API calls. If a code block has no language, it defaults to `plaintext`. Alias: `text`.|
-| `prometheus` | Prometheus configuration examples. |
-| `python` | |
-| `ruby` | Alias: `rb`. |
-| `shell` | Aliases: `bash` or `sh`. |
-| `sql` | |
-| `toml` | Runner configuration examples, and other TOML-formatted configuration files. |
-| `typescript` | Alias: `ts`. |
-| `xml` | |
-| `yaml` | Alias: `yml`. |
-
-For a complete reference on code blocks, see the [Kramdown guide](https://about.gitlab.com/handbook/markdown-guide/#code-blocks).
-
## GitLab SVG icons
> [Introduced](https://gitlab.com/gitlab-org/gitlab-docs/-/issues/384) in GitLab 12.7.
@@ -1379,7 +1339,7 @@ you don't need to supply your username and password each time.
### Disclaimer
Use to describe future functionality only.
-For more information, see [Legal disclaimer for future features](#legal-disclaimer-for-future-features).
+For more information, see [Legal disclaimer for future features](../versions.md#legal-disclaimer-for-future-features).
## Blockquotes
@@ -1429,222 +1389,6 @@ application:
- For elements with a tooltip or hover label, use that label in bold with
matching case. For example, `Select **Add status emoji**`.
-## GitLab versions
-
-GitLab product documentation pages (not including [Contributor and Development](../../index.md)
-pages in the `/development` directory) can include version information to help
-users be aware of recent improvements or additions.
-
-The GitLab Technical Writing team determines which versions of
-documentation to display on this site based on the GitLab
-[Statement of Support](https://about.gitlab.com/support/statement-of-support.html#version-support).
-
-### View older GitLab documentation versions
-
-Older versions of GitLab may no longer have documentation available from `docs.gitlab.com`.
-If documentation for your version is no longer available from `docs.gitlab.com`, you can still view a
-tagged and released set of documentation for your installed version:
-
-- In the [documentation archives](https://docs.gitlab.com/archives/).
-- At the `/help` URL of your GitLab instance.
-- In the documentation repository based on the respective branch (for example,
- the [13.2 branch](https://gitlab.com/gitlab-org/gitlab/-/tree/13-2-stable-ee/doc)).
-
-### Where to put version text
-
-When a feature is added or updated, you can include its version information
-either as a **Version history** item or as an inline text reference.
-
-#### Version text in the **Version History**
-
-If all content in a section is related, add version text after the header for
-the section. The version information must:
-
-- Be surrounded by blank lines.
-- Start with `>`. If there are multiple bullets, each line must start with `> -`.
-- The string must include these words in this order (capitalization doesn't matter):
- - `introduced`, `enabled`, `deprecated`, `changed`, `moved`, `recommended` (as in the
- [feature flag documentation](../feature_flags.md)), `removed`, or `renamed`
- - `in` or `to`
- - `GitLab`
-- Whenever possible, include a link to the completed issue, merge request, or epic
- that introduced the feature. An issue is preferred over a merge request, and
- a merge request is preferred over an epic.
-- Do not include information about the tier, unless documenting a tier change
- (for example, `Feature X [moved](issue-link) to Premium in GitLab 19.2`).
-- Do not link to the pricing page.
- The tier is provided by the [product badge](#product-tier-badges) on the heading.
-
-```markdown
-## Feature name
-
-> [Introduced](<link-to-issue>) in GitLab 11.3.
-
-This feature does something.
-
-## Feature name 2
-
-> - [Introduced](<link-to-issue>) in GitLab 11.3.
-> - [Enabled by default](<link-to-issue>) in GitLab 11.4.
-
-This feature does something else.
-```
-
-If you're documenting elements of a feature, start with the feature name or a gerund:
-
-```markdown
-> - Notifications for expiring tokens [introduced](<link-to-issue>) in GitLab 11.3.
-> - Creating an issue from an issue board [introduced](<link-to-issue>) in GitLab 13.1.
-```
-
-If a feature is moved to another tier:
-
-```markdown
-> - [Moved](<link-to-issue>) from GitLab Ultimate to GitLab Premium in 11.8.
-> - [Moved](<link-to-issue>) from GitLab Premium to GitLab Free in 12.0.
-```
-
-#### Inline version text
-
-If you're adding content to an existing topic, you can add version information
-inline with the existing text.
-
-In this case, add `([introduced/deprecated](<link-to-issue>) in GitLab X.X)`.
-
-Including the issue link is encouraged, but isn't a requirement. For example:
-
-```markdown
-The voting strategy in GitLab 13.4 and later requires the primary and secondary
-voters to agree.
-```
-
-#### Deprecated features
-
-When a feature is deprecated, add `(DEPRECATED)` to the page title or to
-the heading of the section documenting the feature, immediately before
-the tier badge:
-
-```markdown
-<!-- Page title example: -->
-# Feature A (DEPRECATED) **(ALL TIERS)**
-
-<!-- Doc section example: -->
-## Feature B (DEPRECATED) **(PREMIUM SELF)**
-```
-
-Add the deprecation to the version history note (you can include a link
-to a replacement when available):
-
-```markdown
-> - [Deprecated](<link-to-issue>) in GitLab 11.3. Replaced by [meaningful text](<link-to-appropriate-documentation>).
-```
-
-You can also describe the replacement in surrounding text, if available. If the
-deprecation isn't obvious in existing text, you may want to include a warning:
-
-```markdown
-WARNING:
-This feature was [deprecated](link-to-issue) in GitLab 12.3 and replaced by
-[Feature name](link-to-feature-documentation).
-```
-
-If you add `(DEPRECATED)` to the page's title and the document is linked from the docs
-navigation, either remove the page from the nav or update the nav item to include the
-same text before the feature name:
-
-```yaml
- - doc_title: (DEPRECATED) Feature A
-```
-
-In the first major GitLab version after the feature was deprecated, be sure to
-remove information about that deprecated feature.
-
-#### End-of-life for features or products
-
-When a feature or product enters its end-of-life, indicate its status by
-creating a [warning alert](#alert-boxes) directly after its relevant header.
-If possible, link to its deprecation and removal issues.
-
-For example:
-
-```markdown
-WARNING:
-This feature is in its end-of-life process. It is [deprecated](link-to-issue)
-in GitLab X.X, and is planned for [removal](link-to-issue) in GitLab X.X.
-```
-
-After the feature or product is officially deprecated and removed, remove
-its information from the GitLab documentation.
-
-### Versions in the past or future
-
-When describing functionality available in past or future versions, use:
-
-- Earlier, and not older or before.
-- Later, and not newer or after.
-
-For example:
-
-- Available in GitLab 13.1 and earlier.
-- Available in GitLab 12.4 and later.
-- In GitLab 12.2 and earlier, ...
-- In GitLab 11.6 and later, ...
-
-### Promising features in future versions
-
-Do not promise to deliver features in a future release. For example, avoid phrases like,
-"Support for this feature is planned."
-
-We cannot guarantee future feature work, and promises
-like these can raise legal issues. Instead, say that an issue exists.
-For example:
-
-- Support for improvements is tracked `[in this issue](LINK)`.
-- You cannot do this thing, but `[an issue exists](LINK)` to change this behavior.
-
-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.
-
-```markdown
-DISCLAIMER:
-This page contains information related to upcoming products, features, and functionality.
-It is important to note that the information presented is for informational purposes only.
-Please do not rely on this information for purchasing or planning purposes.
-As with all projects, the items mentioned on this page are subject to change or delay.
-The development, release, and timing of any products, features, or functionality remain at the
-sole discretion of GitLab Inc.
-```
-
-It renders on the GitLab documentation site as:
-
-DISCLAIMER:
-This page contains information related to upcoming products, features, and functionality.
-It is important to note that the information presented is for informational purposes only.
-Please do not rely on this information for purchasing or planning purposes.
-As with all projects, the items mentioned on this page are subject to change or delay.
-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 the content in a topic is not ready, use the disclaimer in the topic.
-
-### Removing versions after each major release
-
-When a major GitLab release occurs, we remove all references
-to now-unsupported versions. This removal includes version-specific instructions. For example,
-if GitLab version 12.1 and later are supported,
-instructions for users of GitLab 11 should be removed.
-
-[View the list of supported versions](https://about.gitlab.com/support/statement-of-support.html#version-support).
-
-To view historical information about a feature, review GitLab
-[release posts](https://about.gitlab.com/releases/), or search for the issue or
-merge request where the work was done.
-
## Products and features
Refer to the information in this section when describing products and features
@@ -1664,7 +1408,7 @@ pricing page. For example:
You must assign a tier badge:
-- To all H1 topic headings.
+- To all H1 topic headings, except the pages under `doc/development/*`.
- To topic headings that don't apply to the same tier as the H1.
To add a tier badge to a heading, add the relevant tier badge
@@ -1692,10 +1436,15 @@ functionality is described.
| Only GitLab Premium SaaS and higher tiers (no self-managed instances) | `**(PREMIUM SAAS)**` |
| Only GitLab Ultimate SaaS (no self-managed instances) | `**(ULTIMATE SAAS)**` |
-Topics that mention the `gitlab.rb` file are referring to
-self-managed instances of GitLab. To prevent confusion, include the relevant `TIER SELF`
-tier badge on the highest applicable heading level on
-the page.
+Topics that are only for instance administrators should be badged `<TIER> SELF`. Instance
+administrator documentation often includes sections that mention:
+
+- Changing the `gitlab.rb` or `gitlab.yml` files.
+- Accessing the rails console or running Rake tasks.
+- Doing things in the Admin Area.
+
+These pages should also mention if the tasks can only be accomplished by an
+instance administrator.
## Specific sections
diff --git a/doc/development/documentation/styleguide/word_list.md b/doc/development/documentation/styleguide/word_list.md
index 65f6a0a328b..e7d927de2cf 100644
--- a/doc/development/documentation/styleguide/word_list.md
+++ b/doc/development/documentation/styleguide/word_list.md
@@ -164,7 +164,15 @@ Use lowercase for **boards**, **issue boards**, and **epic boards**.
Use **text box** to refer to the UI field. Do not use **field** or **box**. For example:
-- In the **Variable name** text box, enter `my text`.
+- In the **Variable name** text box, enter a value.
+
+
+## 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:
+
+- **Ordered list item** for items in an ordered list.
+- **Unordered list item** for items in an unordered list.
## button
@@ -318,7 +326,22 @@ Use **active** or **on** instead. ([Vale](../testing.md#vale) rule: [`InclusionA
## enter
-Use **enter** instead of **type** when talking about putting values into text boxes.
+In most cases, use **enter** rather than **type**.
+
+- **Enter** encompasses multiple ways to enter information, including speech and keyboard.
+- **Enter** assumes that the user puts a value in a field and then moves the cursor outside the field (or presses <kbd>Enter</kbd>).
+ **Enter** includes both the entering of the content and the action to validate the content.
+
+For example:
+
+- In the **Variable name** text box, enter a value.
+- In the **Variable name** text box, enter `my text`.
+
+When you use **Enter** to refer to the key on a keyboard, use the HTML `<kbd>` tag:
+
+- To view the list of results, press <kbd>Enter</kbd>.
+
+See also [**type**](#type).
## epic
@@ -356,7 +379,7 @@ Use **box** instead of **field** or **text box**.
Use:
-- In the **Variable name** box, enter `my text`.
+- In the **Variable name** text box, enter `my text`.
Instead of:
@@ -392,6 +415,13 @@ Do not make **GitLab** possessive (GitLab's). This guidance follows [GitLab Trad
**GitLab.com** refers to the GitLab instance managed by GitLab itself.
+## GitLab Flavored Markdown
+
+When possible, spell out [**GitLab Flavored Markdown**](../../../user/markdown.md).
+([Vale](../testing.md#vale) rule: [`GLFM.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/SubstitutionSuggestions.yml))
+
+If you must abbreviate, do not use **GFM**. Use **GLFM** instead.
+
## GitLab SaaS
**GitLab SaaS** refers to the product license that provides access to GitLab.com. It does not refer to the
@@ -518,6 +548,25 @@ Instead of:
Do not use **list** when referring to a [**dropdown list**](#dropdown-list).
Use the full phrase **dropdown list** instead.
+## license
+
+When writing about licenses:
+
+- Do not use variations such as **cloud license**, **offline license**, or **legacy license**.
+- Do not use interchangeably with **subscription**:
+ - A license grants users access to the subscription they purchased, and contains information such as the number of seats they purchased and subscription dates.
+ - A subscription is the subscription tier that the user purchases.
+
+Use:
+
+ - Add a license to your instance.
+ - Purchase a subscription.
+
+Instead of:
+
+ - Buy a license.
+ - Purchase a license.
+
## 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.
@@ -576,6 +625,11 @@ Use lowercase for **merge requests**. If you use **MR** as the acronym, spell it
Use lowercase for **milestones**.
+## n/a, N/A, not applicable
+
+When possible, use **not applicable**. Spelling out the phrase helps non-English speaking users and avoids
+capitalization inconsistencies.
+
## navigate
Do not use **navigate**. Use **go** instead. For example:
@@ -950,7 +1004,17 @@ Use [**2FA** and **two-factor authentication**](#2fa-two-factor-authentication)
## type
-Do not use **type** if you can avoid it. Use **enter** instead.
+Use **type** when the cursor remains in the field you're typing in. For example,
+in a search dialog, you begin typing and the field populates results. You do not
+click out of the field.
+
+For example:
+
+- To view all users named Alex, type `Al`.
+- To view all labels for the documentation team, type `doc`.
+- For a list of quick actions, type `/`.
+
+See also [**enter**](#enter).
## update
@@ -1031,7 +1095,7 @@ Sometimes you might need to use **yet** when writing a task. If you use
**yet**, ensure the surrounding phrases are written
in present tense, active voice.
-[View guidance about how to write about future features](index.md#promising-features-in-future-versions).
+[View guidance about how to write about future features](../versions.md#promising-features-in-future-versions).
([Vale](../testing.md#vale) rule: [`CurrentStatus.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/CurrentStatus.yml))
## you, your, yours
diff --git a/doc/development/documentation/testing.md b/doc/development/documentation/testing.md
index 9facb22669b..81e1eca8724 100644
--- a/doc/development/documentation/testing.md
+++ b/doc/development/documentation/testing.md
@@ -23,6 +23,10 @@ in the relevant projects:
- <https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/.gitlab/ci/docs.gitlab-ci.yml>
- <https://gitlab.com/gitlab-org/omnibus-gitlab/-/blob/master/gitlab-ci-config/gitlab-com.yml>
- <https://gitlab.com/gitlab-org/charts/gitlab/-/blob/master/.gitlab-ci.yml>
+- <https://gitlab.com/gitlab-org/cloud-native/gitlab-operator/-/blob/master/.gitlab-ci.yml>
+
+We also run some documentation tests in the GitLab Development Kit project:
+<https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/.gitlab/ci/test.gitlab-ci.yml>.
## Run tests locally
@@ -144,6 +148,36 @@ synchronized to the other projects. In `omnibus-gitlab`, `gitlab-runner`, and `c
is hard coded for specific projects.
1. Create a merge request and submit it to a technical writer for review and merge.
+## Update linting images
+
+Lint tests run in CI/CD pipelines using images from the `gitlab-docs` [container registry](https://gitlab.com/gitlab-org/gitlab-docs/container_registry).
+
+If a new version of a dependency is released (like a new version of Ruby), we
+should update the images to use the newer version. Then, we can update the configuration
+files in each of our documentation projects to point to the new image.
+
+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. 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.
+ ([Example job output](https://gitlab.com/gitlab-org/gitlab-docs/-/jobs/2335033884#L334))
+1. Verify that the new image was added to the container registry.
+1. Open merge requests to update each of these configuration files to point to the new image.
+ In each merge request, include a small doc update to trigger the job that uses the image.
+ - <https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/ci/docs.gitlab-ci.yml> ([Example MR](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/85177))
+ - <https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/.gitlab/ci/test.gitlab-ci.yml> ([Example MR](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/3408))
+ - <https://gitlab.com/gitlab-org/omnibus-gitlab/-/blob/master/gitlab-ci-config/gitlab-com.yml> ([Example MR](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/6037))
+ - <https://gitlab.com/gitlab-org/charts/gitlab/-/blob/master/.gitlab-ci.yml> ([Example MR](https://gitlab.com/gitlab-org/charts/gitlab/-/merge_requests/2511))
+ - <https://gitlab.com/gitlab-org/cloud-native/gitlab-operator/-/blob/master/.gitlab-ci.yml> ([Example MR](https://gitlab.com/gitlab-org/cloud-native/gitlab-operator/-/merge_requests/462))
+ - <https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/.gitlab/ci/test.gitlab-ci.yml> ([Example MR](https://gitlab.com/gitlab-org/gitlab-development-kit/-/merge_requests/2417))
+1. In each merge request, check the relevant job output to confirm the updated image was
+ used for the test. ([Example job output](https://gitlab.com/gitlab-org/charts/gitlab/-/jobs/2335470260#L24))
+1. Assign the merge requests to any technical writer to review and merge.
+
## Local linters
To help adhere to the [documentation style guidelines](styleguide/index.md), and improve the content
@@ -173,6 +207,7 @@ markdownlint configuration is found in the following projects:
- [`omnibus-gitlab`](https://gitlab.com/gitlab-org/omnibus-gitlab)
- [`charts`](https://gitlab.com/gitlab-org/charts/gitlab)
- [`gitlab-development-kit`](https://gitlab.com/gitlab-org/gitlab-development-kit)
+- [`gitlab-operator`](https://gitlab.com/gitlab-org/cloud-native/gitlab-operator)
This configuration is also used in build pipelines.
@@ -311,7 +346,7 @@ To configure Vale in your editor, install one of the following as appropriate:
- Visual Studio Code [`errata-ai.vale-server` extension](https://marketplace.visualstudio.com/items?itemName=errata-ai.vale-server).
You can configure the plugin to [display only a subset of alerts](#show-subset-of-vale-alerts).
- Vim [ALE plugin](https://github.com/dense-analysis/ale).
-- Jetbrains IDEs - No plugin exists, but
+- 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).
diff --git a/doc/development/documentation/versions.md b/doc/development/documentation/versions.md
new file mode 100644
index 00000000000..0f2bdca4c73
--- /dev/null
+++ b/doc/development/documentation/versions.md
@@ -0,0 +1,232 @@
+---
+info: For assistance with this Style Guide page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-other-projects-and-subjects.
+stage: none
+group: unassigned
+description: 'Writing styles, markup, formatting, and other standards for GitLab Documentation.'
+---
+
+# Documenting product versions
+
+The GitLab product documentation includes version-specific information,
+including when features were introduced and when they were updated or removed.
+
+## View older documentation versions
+
+Previous versions of the documentation are available on `docs.gitlab.com`.
+To view a previous version, select the **Versions** button in the top right.
+
+To view versions that are not available on `docs.gitlab.com`:
+
+- View the [documentation archives](https://docs.gitlab.com/archives/).
+- Go to the GitLab repository and select the version-specific branch. For example,
+ the [13.2 branch](https://gitlab.com/gitlab-org/gitlab/-/tree/13-2-stable-ee/doc) has the
+ documentation for GitLab 13.2.
+
+## Documenting version-specific features
+
+When a feature is added or updated, you can include its version information
+either as a **Version history** bullet or as an inline text reference.
+
+You do not need to add version information on the pages in the `/development` directory.
+
+### Add a **Version history** item
+
+If all content in a topic is related, add a version history item after the topic heading.
+For example:
+
+```markdown
+## Feature name
+
+> [Introduced](<link-to-issue>) in GitLab 11.3.
+
+This feature does something.
+```
+
+The item text must include these words in order. Capitalization doesn't matter.
+
+- `introduced`, `enabled`, `deprecated`, `changed`, `moved`, `recommended`, `removed`, or `renamed`
+- `in` or `to`
+- `GitLab`
+
+If possible, include a link to the related issue, merge request, or epic.
+Do not link to the pricing page. Do not include the subscription tier.
+
+#### Introducing a new feature
+
+If you use `introduced`, start the sentence with the feature name or a gerund:
+
+```markdown
+> - Notifications for expiring tokens [introduced](<link-to-issue>) in GitLab 11.3.
+> - Creating an issue from an issue board [introduced](<link-to-issue>) in GitLab 13.1.
+```
+
+#### Moving subscription tiers
+
+If a feature is moved to another subscription tier, use `moved`:
+
+```markdown
+> - [Moved](<link-to-issue>) from GitLab Ultimate to GitLab Premium in 11.8.
+> - [Moved](<link-to-issue>) from GitLab Premium to GitLab Free in 12.0.
+```
+
+### Inline version text
+
+If you're adding content to an existing topic, you can add version information
+inline with the existing text. If possible, include a link to the related issue,
+merge request, or epic. For example:
+
+```markdown
+The voting strategy [in GitLab 13.4 and later](<link-to-issue>) requires the primary and secondary
+voters to agree.
+```
+
+## Deprecations and removals
+
+When features are deprecated and removed, update the related documentation.
+
+API documentation follows these guidelines, but the GraphQL docs use
+a [separate process](../api_graphql_styleguide.md#deprecating-schema-items).
+
+### Deprecate a page or topic
+
+To deprecate a page or topic:
+
+1. Add `(deprecated)` after the title. Use a warning to explain when it was deprecated,
+ when it will be removed, and the replacement feature.
+
+ ```markdown
+ ## Title (deprecated) **(ULTIMATE SELF)**
+
+ WARNING:
+ This feature was [deprecated](<link-to-issue>) in GitLab 14.8
+ and is planned for removal in 15.4. Use [feature X](<link-to-issue>) instead.
+ ```
+
+ If you're not sure when the feature will be removed or no
+ replacement feature exists, you don't need to add this information.
+
+1. If the deprecation is a breaking change, add this text:
+
+ ```markdown
+ This change is a breaking change.
+ ```
+
+ You can add any additional context-specific details that might help users.
+
+1. Open a merge request to add the word `(deprecated)` to the left nav, after the page title.
+
+### Remove a page
+
+Mark content as removed during the release the feature was removed.
+The title and a removed indicator remains until three months after the removal.
+
+To remove a page:
+
+1. Leave the page title. Remove all other content, including the version history items and the word `WARNING:`.
+1. After the title, change `(deprecated)` to `(removed)`.
+1. Update the YAML metadata:
+ - For `remove_date`, set the value to a date three months after
+ the release when the feature was removed.
+ - For the `redirect_to`, set a path to a file that makes sense. If no obvious
+ page exists, use the docs home page.
+
+ ```markdown
+ ---
+ stage: Enablement
+ group: Global Search
+ 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
+ remove_date: '2022-08-02'
+ redirect_to: '../newpath/to/file/index.md'
+ ---
+
+ # Title (removed) **(ULTIMATE SELF)**
+
+ This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/351963) in GitLab 14.8
+ and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/351963) in 15.0.
+ Use [feature X](<link-to-issue>) instead.
+ ```
+
+1. Remove the page's entry from the global navigation by editing [`navigation.yaml`](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/content/_data/navigation.yaml) in `gitlab-docs`.
+
+This content is removed from the documentation as part of the Technical Writing team's
+[regularly scheduled tasks](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#regularly-scheduled-tasks).
+
+### Remove a topic
+
+To remove a topic:
+
+1. Leave the title and the details of the deprecation and removal. Remove all other content,
+ including the version history items and the word `WARNING:`.
+1. Add `(removed)` after the title.
+1. Add the following HTML comments above and below the topic.
+ For the `remove_date`, set a date three months after the release where it was removed.
+
+ ```markdown
+ <!--- start_remove The following content will be removed on remove_date: '2023-08-22' -->
+
+ ## Title (removed) **(ULTIMATE SELF)**
+
+ This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/351963) in GitLab 14.8
+ and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/351963) in 15.0.
+ Use [feature X](<link-to-issue>) instead.
+
+ <!--- end_remove -->
+ ```
+
+This content is removed from the documentation as part of the Technical Writing team's
+[regularly scheduled tasks](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#regularly-scheduled-tasks).
+
+## Which versions are removed
+
+GitLab supports the current major version and two previous major versions.
+For example, if 14.0 is the current major version, all major and minor releases of
+GitLab 14.0, 13.0 and 12.0 are supported.
+
+[View the list of supported versions](https://about.gitlab.com/support/statement-of-support.html#version-support).
+
+If you see version history items or inline text that refers to unsupported versions, you can remove it.
+
+Historical feature information is available in [release posts](https://about.gitlab.com/releases/)
+or by searching for the issue or merge request where the work was done.
+
+## Promising features in future versions
+
+Do not promise to deliver features in a future release. For example, avoid phrases like,
+"Support for this feature is planned."
+
+We cannot guarantee future feature work, and promises
+like these can raise legal issues. Instead, say that an issue exists.
+For example:
+
+- Support for improvements is tracked `[in this issue](LINK)`.
+- You cannot do this thing, but `[an issue exists](LINK)` to change this behavior.
+
+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.
+
+```markdown
+DISCLAIMER:
+This page contains information related to upcoming products, features, and functionality.
+It is important to note that the information presented is for informational purposes only.
+Please do not rely on this information for purchasing or planning purposes.
+As with all projects, the items mentioned on this page are subject to change or delay.
+The development, release, and timing of any products, features, or functionality remain at the
+sole discretion of GitLab Inc.
+```
+
+It renders on the GitLab documentation site as:
+
+DISCLAIMER:
+This page contains information related to upcoming products, features, and functionality.
+It is important to note that the information presented is for informational purposes only.
+Please do not rely on this information for purchasing or planning purposes.
+As with all projects, the items mentioned on this page are subject to change or delay.
+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 the content in a topic is not ready, use the disclaimer in the topic.
diff --git a/doc/development/documentation/workflow.md b/doc/development/documentation/workflow.md
index a12af51e436..fb43a2e995a 100644
--- a/doc/development/documentation/workflow.md
+++ b/doc/development/documentation/workflow.md
@@ -151,7 +151,7 @@ Remember:
Ensure the following if skipping an initial Technical Writer review:
- [Product badges](styleguide/index.md#product-tier-badges) are applied.
-- The GitLab [version](styleguide/index.md#gitlab-versions) that
+- The GitLab [version](versions.md) that
introduced the feature is included.
- Changes to headings don't affect in-app hyperlinks.
- Specific [user permissions](../../user/permissions.md) are documented.