diff options
Diffstat (limited to 'doc/development/documentation')
| -rw-r--r-- | doc/development/documentation/feature_flags.md | 13 | ||||
| -rw-r--r-- | doc/development/documentation/restful_api_styleguide.md | 62 | ||||
| -rw-r--r-- | doc/development/documentation/site_architecture/index.md | 75 | ||||
| -rw-r--r-- | doc/development/documentation/structure.md | 4 | ||||
| -rw-r--r-- | doc/development/documentation/styleguide/index.md | 349 | ||||
| -rw-r--r-- | doc/development/documentation/styleguide/word_list.md | 74 | ||||
| -rw-r--r-- | doc/development/documentation/testing.md | 37 | ||||
| -rw-r--r-- | doc/development/documentation/versions.md | 232 | ||||
| -rw-r--r-- | doc/development/documentation/workflow.md | 2 |
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. |