diff options
Diffstat (limited to 'doc/development/documentation')
| -rw-r--r-- | doc/development/documentation/alpha_beta.md | 32 | ||||
| -rw-r--r-- | doc/development/documentation/feature_flags.md | 2 | ||||
| -rw-r--r-- | doc/development/documentation/index.md | 37 | ||||
| -rw-r--r-- | doc/development/documentation/redirects.md | 24 | ||||
| -rw-r--r-- | doc/development/documentation/site_architecture/global_nav.md | 3 | ||||
| -rw-r--r-- | doc/development/documentation/site_architecture/index.md | 2 | ||||
| -rw-r--r-- | doc/development/documentation/styleguide/index.md | 39 | ||||
| -rw-r--r-- | doc/development/documentation/styleguide/word_list.md | 138 | ||||
| -rw-r--r-- | doc/development/documentation/testing.md | 16 | ||||
| -rw-r--r-- | doc/development/documentation/topic_types/glossary.md | 70 | ||||
| -rw-r--r-- | doc/development/documentation/topic_types/index.md | 59 | ||||
| -rw-r--r-- | doc/development/documentation/topic_types/task.md | 2 | ||||
| -rw-r--r-- | doc/development/documentation/topic_types/tutorial.md | 18 |
13 files changed, 303 insertions, 139 deletions
diff --git a/doc/development/documentation/alpha_beta.md b/doc/development/documentation/alpha_beta.md index 4b5c24d512f..d421aae3cb9 100644 --- a/doc/development/documentation/alpha_beta.md +++ b/doc/development/documentation/alpha_beta.md @@ -4,40 +4,46 @@ stage: none group: unassigned --- -# Document Alpha, Beta, LA features +# Documenting Experiment and Beta features Some features are not generally available and are instead considered -[Alpha, Beta, or Limited Availability](../../policy/alpha-beta-support.md). +[Experiment or Beta](../../policy/alpha-beta-support.md). When you document a feature in one of these three statuses: -- Add `(Alpha)`, `(Beta)`, or `(Limited Availability)` in parentheses after the page or topic title. -- Do not include `(Alpha)`, `(Beta)`, or `(Limited Availability)` in the left nav. +- Add `(Experiment)` or `(Beta)` in parentheses after the page or topic title. +- Do not include `(Experiment)` or `(Beta)` in the left nav. - Ensure the version history lists the feature's status. These features are usually behind a feature flag, which follow [these documentation guidelines](feature_flags.md). If you add details of how users should enroll, or how to contact the team with issues, -the `FLAG:` note should be above these details. For example: +the `FLAG:` note should be above these details. + +For example: ```markdown -## Great new feature (Alpha) +## Great new feature (Experiment) + +> [Introduced](link) in GitLab 15.10. This feature is an [Experiment](<link_to>/policy/alpha-beta-support.md). FLAG: On self-managed GitLab, by default this feature is not available. -To make it available, ask an administrator to enable the feature flag named example_flag. +To make it available, ask an administrator to enable the feature flag named `example_flag`. On GitLab.com, this feature is not available. This feature is not ready for production use. Use this great new feature when you need to do this new thing. -This feature is in Alpha. To join the list of users testing this feature, -do this thing. If you find a bug, [open an issue](link). +This feature is an [Experiment](<link_to>/policy/alpha-beta-support.md). To join +the list of users testing this feature, do this thing. If you find a bug, +[open an issue](link). ``` -When the feature is released, remove: +When the feature is ready for production, remove: - The text in parentheses. -- Any language about the feature not being ready for production. -- The feature flag information. +- Any language about the feature not being ready for production in the body + description. +- The feature flag information if available. -Ensure the version history is up-to-date. +Ensure the version history is up-to-date by adding a note about the production release. diff --git a/doc/development/documentation/feature_flags.md b/doc/development/documentation/feature_flags.md index 986252eedac..854faa839ef 100644 --- a/doc/development/documentation/feature_flags.md +++ b/doc/development/documentation/feature_flags.md @@ -17,7 +17,7 @@ When the state of a feature flag changes, the developer who made the change Every feature introduced to the codebase, even if it's behind a disabled feature flag, must be documented. For more information, see -[the discussion that led to this decision](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/47917#note_459984428). [Alpha, Beta, or Limited Availability](../../policy/alpha-beta-support.md) features are usually behind a feature flag, and must also be documented. For more information, see [Document Alpha, Beta, LA features](alpha_beta.md). +[the discussion that led to this decision](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/47917#note_459984428). [Experiment or Beta](../../policy/alpha-beta-support.md) features are usually behind a feature flag, and must also be documented. For more information, see [Document Experiment or Beta features](alpha_beta.md). When the feature is [implemented in multiple merge requests](../feature_flags/index.md#feature-flags-in-gitlab-development), discuss the plan with your technical writer. diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index d1f5ee8f9f3..c9f31b36e3f 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -114,21 +114,6 @@ The following metadata should be added when a page is moved to another location: - `redirect_to`: The relative path and filename (with an `.md` extension) of the location to which visitors should be redirected for a moved page. [Learn more](redirects.md). -- `disqus_identifier`: Identifier for Disqus commenting system. Used to keep - comments with a page that has been moved to a new URL. - [Learn more](redirects.md#redirections-for-pages-with-disqus-comments). - -### Comments metadata - -The [docs website](site_architecture/index.md) has comments (provided by Disqus) -enabled by default. In case you want to disable them (for example in index pages), -set it to `false`: - -```yaml ---- -comments: false ---- -``` ### Additional page metadata @@ -353,28 +338,6 @@ feedback: false The default is to leave it there. If you want to omit it from a document, you must check with a technical writer before doing so. -## Disqus - -We have integrated the docs site with Disqus (introduced by -[!151](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/151)), -allowing our users to post comments. - -To omit only the comments from the feedback section, use the following key in -the front matter: - -```yaml ---- -comments: false ---- -``` - -We're hiding comments only in main index pages, such as [the main documentation index](../../index.md), -since its content is too broad to comment on. Before omitting Disqus, you must -check with a technical writer. - -Note that after adding `feedback: false` to the front matter, it will omit -Disqus, therefore, don't add both keys to the same document. - The click events in the feedback section are tracked with Google Tag Manager. The conversions can be viewed on Google Analytics by navigating to **Behavior > Events > Top events > docs**. diff --git a/doc/development/documentation/redirects.md b/doc/development/documentation/redirects.md index 4cfe8be713a..068c1e84a0f 100644 --- a/doc/development/documentation/redirects.md +++ b/doc/development/documentation/redirects.md @@ -81,7 +81,6 @@ To redirect a page to another page in the same repository: - Replace both instances of `../newpath/to/file/index.md` with the new file path. - Replace both instances of `YYYY-MM-DD` with the expiration date, as explained in the template. -1. If the page has Disqus comments, follow [the steps for pages with Disqus comments](#redirections-for-pages-with-disqus-comments). 1. If the page had images that aren't used on any other pages, delete them. After your changes are committed, search for and update all links that point to the old file: @@ -158,26 +157,3 @@ If you create a new page and then rename it before it's added to a release on th Instead of following that procedure, ask a Technical Writer to manually add the redirect to [`redirects.yaml`](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/content/_data/redirects.yaml). - -## Redirections for pages with Disqus comments - -If the documentation page being relocated already has Disqus comments, -we need to preserve the Disqus thread. - -Disqus uses an identifier per page, and for <https://docs.gitlab.com>, the page identifier -is configured to be the page URL. Therefore, when we change the document location, -we need to preserve the old URL as the same Disqus identifier. - -To do that, add to the front matter the variable `disqus_identifier`, -using the old URL as value. For example, let's say we moved the document -available under `https://docs.gitlab.com/my-old-location/README.html` to a new location, -`https://docs.gitlab.com/my-new-location/index.html`. - -Into the **new document** front matter, we add the following information. You must -include the filename in the `disqus_identifier` URL, even if it's `index.html` or `README.html`. - -```yaml ---- -disqus_identifier: 'https://docs.gitlab.com/my-old-location/README.html' ---- -``` diff --git a/doc/development/documentation/site_architecture/global_nav.md b/doc/development/documentation/site_architecture/global_nav.md index ef6f3c0ae18..3e0534220a8 100644 --- a/doc/development/documentation/site_architecture/global_nav.md +++ b/doc/development/documentation/site_architecture/global_nav.md @@ -69,8 +69,7 @@ Sometimes pages for deprecated features are not in the global nav, depending on All other pages should be in the global nav. The technical writing team runs a report to determine which pages are not in the nav. -For now this report is manual, but [an issue exists](https://gitlab.com/gitlab-org/gitlab-docs/-/issues/1212) -to automate it. +The team reviews this list each month. ### Where to add diff --git a/doc/development/documentation/site_architecture/index.md b/doc/development/documentation/site_architecture/index.md index d4553614fad..849308f3086 100644 --- a/doc/development/documentation/site_architecture/index.md +++ b/doc/development/documentation/site_architecture/index.md @@ -33,7 +33,7 @@ Then you can use one of these approaches: of the documentation in the external repository. The landing page is indexed and searchable on <https://docs.gitlab.com>, but the rest of the documentation is not. For example, the [GitLab Workflow extension for VS Code](../../../user/project/repository/vscode.md). - We do not encourage the use of [pages with lists of links](../topic_types/index.md#topics-and-resources), + We do not encourage the use of [pages with lists of links](../topic_types/index.md#pages-and-topics-to-avoid), so only use this option if the recommended options are not feasible. ## Monthly release process (versions) diff --git a/doc/development/documentation/styleguide/index.md b/doc/development/documentation/styleguide/index.md index 7f69a1f0d54..2925a0f0371 100644 --- a/doc/development/documentation/styleguide/index.md +++ b/doc/development/documentation/styleguide/index.md @@ -60,7 +60,7 @@ GitLab adds all troubleshooting information to the documentation, no matter how unlikely a user is to encounter a situation. GitLab Support maintains their own -[troubleshooting content](../../../administration/index.md#support-team-documentation) +[troubleshooting content](../../../administration/troubleshooting/index.md) in the GitLab documentation. ### The documentation includes all media types @@ -718,6 +718,15 @@ This is overridden by the [documentation-specific punctuation rules](#punctuatio Links help the docs adhere to the [single source of truth](#documentation-is-the-single-source-of-truth-ssot) principle. +However, you should avoid putting too many links on any page. Too many links can hinder readability. + +- Do not duplicate links on the same page. For example, on **Page A**, do not link to **Page B** multiple times. +- Avoid multiple links in a single paragraph. +- Avoid multiple links in a single task. +- On any one page, try not to use more than 15 links to other pages. +- Consider using [Related topics](../topic_types/index.md#related-topics) to reduce links that interrupt the flow of a task. +- Try to avoid anchor links to sections on the same page. Let users rely on the right navigation instead. + ### Links within the same repository To link to another page in the same repository, @@ -1449,7 +1458,7 @@ For tab titles, be brief and consistent. Ensure they are parallel, and start eac For example: - `Linux package (Omnibus)`, `Helm chart (Kubernetes)` (when documenting configuration edits, follow the - [configuration edits guide](#configuration-documentation-for-different-installation-methods)) + [configuration edits guide](#how-to-document-different-installation-methods)) - `15.1 and earlier`, `15.2 and later` Until we implement automated testing for broken links to tabs ([Issue 1355](https://gitlab.com/gitlab-org/gitlab-docs/-/issues/1355)), do not link directly to a single tab, even though they do have unique URL parameters. @@ -1546,24 +1555,28 @@ If the document resides outside of the `doc/` directory, use the full path instead of the relative link: `https://docs.gitlab.com/ee/administration/restart_gitlab.html`. -### Installation guide - -In [step 2 of the installation guide](../../../install/installation.md#2-ruby), -we install Ruby from source. To update the guide for a new Ruby version: +### How to document different installation methods -- Change the version throughout the code block. -- Replace the sha256sum. It's available on the - [downloads page](https://www.ruby-lang.org/en/downloads/) of the Ruby website. +GitLab supports five official installation methods. If you're referring to +words as part of sentences and titles, use the following phrases: -### Configuration documentation for different installation methods +- Linux package +- Helm chart +- GitLab Operator +- Docker +- Self-compiled -GitLab supports four installation methods: +It's OK to add the explanatory parentheses when +[using tabs](#use-tabs-to-describe-a-self-managed-configuration-procedure): - Linux package (Omnibus) - Helm chart (Kubernetes) +- GitLab Operator (Kubernetes) - Docker - Self-compiled (source) +### Use tabs to describe a self-managed configuration procedure + Configuration procedures can require users to edit configuration files, reconfigure GitLab, or restart GitLab. In this case: @@ -1576,8 +1589,8 @@ GitLab, or restart GitLab. In this case: - The final step to reconfigure or restart GitLab can be used verbatim since it's the same every time. -You can copy and paste the following snippet when describing a configuration -edit: +When describing a configuration edit, you can use and edit to your liking the +following snippet: <!-- markdownlint-disable tabs-blank-lines --> ````markdown diff --git a/doc/development/documentation/styleguide/word_list.md b/doc/development/documentation/styleguide/word_list.md index 1ea95367d01..eb0576d0c05 100644 --- a/doc/development/documentation/styleguide/word_list.md +++ b/doc/development/documentation/styleguide/word_list.md @@ -149,13 +149,6 @@ Instead of: This phrasing is more active and is from the user perspective, rather than the person who implemented the feature. [View details in the Microsoft style guide](https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/a/allow-allows). -## Alpha - -Use uppercase for **Alpha**. For example: **The XYZ feature is in Alpha.** or **This Alpha release is ready to test.** - -You might also want to link to [this section](../../../policy/alpha-beta-support.md#alpha-features) -in the handbook when writing about Alpha features. - ## analytics Use lowercase for **analytics** and its variations, like **contribution analytics** and **issue analytics**. @@ -214,7 +207,7 @@ Try to avoid **below** when referring to an example or table in a documentation Use uppercase for **Beta**. For example: **The XYZ feature is in Beta.** or **This Beta release is ready to test.** -You might also want to link to [this section](../../../policy/alpha-beta-support.md#beta-features) +You might also want to link to [this section](../../../policy/alpha-beta-support.md#beta) in the handbook when writing about Beta features. ## blacklist @@ -286,8 +279,7 @@ CI/CD is always uppercase. No need to spell it out on first use. ## CI/CD minutes -Use **CI/CD minutes** instead of **CI minutes**, **pipeline minutes**, **pipeline minutes quota**, or -**CI pipeline minutes**. This decision was made in [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/342813). +Do not use **CI/CD minutes**. This term was renamed to [**compute credits**](#compute-credits). ## click @@ -297,7 +289,7 @@ Do not use **click**. Instead, use **select** with buttons, links, menu items, a ## cloud native When you're talking about using a Kubernetes cluster to host GitLab, you're talking about a **cloud-native version of GitLab**. -This version is different than the larger, more monolithic **Omnibus package** that is used to deploy GitLab. +This version is different than the larger, more monolithic **Linux package** that is used to deploy GitLab. You can also use **cloud-native GitLab** for short. It should be hyphenated and lowercase. @@ -305,6 +297,25 @@ You can also use **cloud-native GitLab** for short. It should be hyphenated and Use **collapse** instead of **close** when you are talking about expanding or collapsing a section in the UI. +## command line + +Use **From the command line** to introduce commands. + +Hyphenate when using as an adjective. For example, **a command-line tool**. + +## compute credits + +Use **compute credits** instead of these (or similar) terms: + +- **CI/CD minutes** +- **CI minutes** +- **pipeline minutes** +- **CI pipeline minutes** +- **pipeline minutes quota** + +This language is still being standardized in the documentation and UI beginning in March, 2023. +For more information, see [issue 5218](https://gitlab.com/gitlab-com/Product/-/issues/5218). + ## confirmation dialog Use **confirmation dialog** to describe the dialog box that asks you to confirm your action. For example: @@ -480,6 +491,13 @@ Instead of: Use **expand** instead of **open** when you are talking about expanding or collapsing a section in the UI. +## Experiment + +Use uppercase for **Experiment**. For example: **The XYZ feature is an Experiment.** or **This Experiment is ready to test.** + +You might also want to link to [this section](../../../policy/alpha-beta-support.md#experiment) +in the handbook when writing about Experiment features. + ## FAQ We want users to find information quickly, and they rarely search for the term **FAQ**. @@ -518,6 +536,17 @@ Filtering is different from [searching](#search). Do not use **foo** in product documentation. You can use it in our API and contributor documentation, but try to use a clearer and more meaningful example instead. +## fork + +A **fork** is a project that was created from a **upstream project** by using the +[forking process](../../../topics/git/terminology.md#fork). + +The **upstream project** (also known as the **source project**) and the **fork** have a **fork relationship** and are +**linked**. + +If the [**fork relationship** is removed](../../../user/project/repository/forking_workflow.md#unlink-a-fork), the +**fork** is **unlinked** from the **upstream project**. + ## future tense When possible, use present tense instead of future tense. For example, use **after you execute this command, GitLab displays the result** instead of **after you execute this command, GitLab will display the result**. ([Vale](../testing.md#vale) rule: [`FutureTense.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/FutureTense.yml)) @@ -552,6 +581,10 @@ Do not use **the `gitlab` chart**, **the GitLab Chart**, or **the cloud-native c You use the **GitLab Helm chart** to deploy **cloud-native GitLab** in a Kubernetes cluster. +If you use it in a context of describing the +[different installation methods](index.md#how-to-document-different-installation-methods). +use `Helm chart (Kubernetes)`. + ## GitLab Pages For consistency and branding, use **GitLab Pages** rather than **Pages**. @@ -561,7 +594,14 @@ you can use **Pages** thereafter. ## GitLab Runner -Use title case for **GitLab Runner**. This is the product you install. See also [runners](#runner-runners) and [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/233529). +Use title case for **GitLab Runner**. This is the product you install. For more information about the decision for this usage, +see [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/233529). + +See also: + +- [runners](#runner-runners) +- [runner managers](#runner-manager-runner-managers) +- [runner workers](#runner-worker-runner-workers) ## GitLab SaaS @@ -643,13 +683,29 @@ Do not use Latin abbreviations. Use **that is** instead. ([Vale](../testing.md#v Do not use **in order to**. Use **to** instead. ([Vale](../testing.md#vale) rule: [`Wordy.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/Wordy.yml)) +## Installation from source + +When referring to the installation method using the self-compiled code, refer to it +as **self-compiled**. + +Use: + +- For self-compiled installations... + +Instead of: + +- For installations from source... + +For more information, see the +[different installation methods](index.md#how-to-document-different-installation-methods). + ## -ing words Remove **-ing** words whenever possible. They can be difficult to translate, and more precise terms are usually available. For example: - Instead of **The files using storage are deleted**, use **The files that use storage are deleted**. -- Instead of **Delete files using the Edit button**, use **Delete files by using the Edit button**. +- Instead of **Delete files using the Edit button**, use **Use the Edit button to delete files**. - Instead of **Replicating your server is required**, use **You must replicate your server**. ## issue @@ -814,6 +870,23 @@ Use lowercase for **merge requests**. If you use **MR** as the acronym, spell it Use lowercase for **milestones**. +## Minimal Access + +When writing about the Minimal Access role: + +- Use a capital **M** and a capital **A**. +- Write it out: + - Use: if you are assigned the Minimal Access role + - Instead of: if you are a Minimal Access user + +- When the Minimal Access role is the minimum required role: + - Use: at least the Minimal Access role + - Instead of: the Minimal Access role or higher + +Do not use bold. + +Do not use **Minimal Access permissions**. A user who is assigned the Minimal Access role has a set of associated permissions. + ## n/a, N/A, not applicable When possible, use **not applicable**. Spelling out the phrase helps non-English speaking users and avoids @@ -876,6 +949,22 @@ Instead of: - Note that you can change the settings. +## Omnibus GitLab + +When referring to the installation method that uses the Linux package, refer to it +as **Linux package**. + +Use: + +- For installations that use the Linux package... + +Instead of: + +- For installations that use Omnibus GitLab... + +For more information, see the +[different installation methods](index.md#how-to-document-different-installation-methods). + ## on When documenting how to select high-level UI elements, use the word **on**. @@ -969,6 +1058,10 @@ Use lowercase for **personal access token**. Do not use **please**. For details, see the [Microsoft style guide](https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/p/please). +## Premium + +Use **Premium**, in uppercase, for the subscription tier. + ## prerequisites Use **prerequisites** when documenting the steps before a task. Do not use **requirements**. @@ -1079,6 +1172,14 @@ Use lowercase for **runners**. These are the agents that run CI/CD jobs. See als When referring to runners, if you have to specify that the runners are installed on a customer's GitLab instance, use **self-managed** rather than **self-hosted**. +## runner manager, runner managers + +Use lowercase for **runner managers**. These are a type of runner that can create multiple runners for autoscaling. See also [GitLab Runner](#gitlab-runner). + +## runner worker, runner workers + +Use lowercase for **runner workers**. This is the process created by the runner on the host computing platform to run jobs. See also [GitLab Runner](#gitlab-runner). + ## (s) Do not use **(s)** to make a word optionally plural. It can slow down comprehension. For example: @@ -1239,6 +1340,13 @@ Use lowercase for **terminal**. For example: - Open a terminal. - From a terminal, run the `docker login` command. +## Terraform Module Registry + +Use title case for the GitLab Terraform Module Registry, but use lowercase `m` when +talking about non-specific modules. For example: + +- You can publish a Terraform module to your project's Terraform Module Registry. + ## text box Use **text box** instead of **field** or **box** when referring to the UI element. @@ -1314,6 +1422,10 @@ For example: See also [**enter**](#enter). +## Ultimate + +Use **Ultimate**, in uppercase, for the subscription tier. + ## units of measurement Use a space between the number and the unit of measurement. For example, **128 GB**. diff --git a/doc/development/documentation/testing.md b/doc/development/documentation/testing.md index 4f61b2424eb..4a7e206da20 100644 --- a/doc/development/documentation/testing.md +++ b/doc/development/documentation/testing.md @@ -49,17 +49,21 @@ To run tests locally, it's important to: ### Lint checks Lint checks are performed by the [`lint-doc.sh`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/scripts/lint-doc.sh) -script and can be executed as follows: +script and can be executed with the help of a Rake task as follows: -1. Go to the `gitlab` directory. +1. Go to your `gitlab` directory. 1. Run: ```shell - MD_DOC_PATH=path/to/my_doc.md scripts/lint-doc.sh + rake lint:markdown ``` -Where `MD_DOC_PATH` points to the file or directory you would like to run lint checks for. -If you omit it completely, it defaults to the `doc/` directory. +To specify a single file or directory you would like to run lint checks for, run: + +```shell +MD_DOC_PATH=path/to/my_doc.md rake lint:markdown +``` + The output should be similar to: ```plaintext @@ -77,7 +81,7 @@ The output should be similar to: This requires you to either: - Have the [required lint tools installed](#local-linters) on your computer. -- A working Docker installation, in which case an image with these tools pre-installed is used. +- A working Docker or containerd installation, to use an image with these tools pre-installed. ### Documentation link tests diff --git a/doc/development/documentation/topic_types/glossary.md b/doc/development/documentation/topic_types/glossary.md new file mode 100644 index 00000000000..4985101a391 --- /dev/null +++ b/doc/development/documentation/topic_types/glossary.md @@ -0,0 +1,70 @@ +--- +stage: none +group: Style Guide +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Glossary topic type + +A glossary provides a list of unfamiliar terms and their definitions to help users understand a specific +GitLab feature. + +Each glossary item provides a single term and its associated definition. The definition should answer the questions: + +- **What** is this? +- **Why** would you use it? + +For glossary terms: + +- Do not use jargon. +- Do not use internal terminology or acronyms. +- Ensure the correct usage is defined in the [word list](../styleguide/word_list.md). + +## Alternatives to glossaries + +Glossaries should provide short, concise term-definition pairs. + +- If a definition requires more than a brief explanation, use a concept topic instead. +- If you find yourself explaining how to use the feature, use a task topic instead. + +## Glossary example + +Glossary topics should be in this format. Use an unordered list primarily. You can use a table if you need to apply +additional categorization. + +Try to include glossary topics on pages that explain the feature, rather than as a standalone page. + +```markdown +## FeatureName glossary + +This glossary provides definitions for terms related to FeatureName. + +- **Term A**: Term A does this thing. +- **Term B**: Term B does this thing. +- **Term C**: Term C does this thing. +``` + +If you use the table format: + +```markdown +## FeatureName glossary + +This glossary provides definitions for terms related to FeatureName. + +| Term | Definition | Additional category | +|--------|-------------------------|---------------------| +| Term A | Term A does this thing. | | +| Term B | Term B does this thing. | | +| Term C | Term C does this thing. | | +``` + +## Glossary topic titles + +Use `FeatureName glossary`. + +Don't use alternatives to `glossary`. For example: + +- `Terminology` +- `Glossary of terms` +- `Glossary of common terms` +- `Definitions` diff --git a/doc/development/documentation/topic_types/index.md b/doc/development/documentation/topic_types/index.md index cfc231c268a..37ed876fc59 100644 --- a/doc/development/documentation/topic_types/index.md +++ b/doc/development/documentation/topic_types/index.md @@ -16,22 +16,52 @@ Each topic on a page should be one of the following topic types: Even if a page is short, the page usually starts with a concept and then includes a task or reference topic. -The tech writing team sometimes uses the acronym `CTRT` to refer to our topic types. +The tech writing team sometimes uses the acronym `CTRT` to refer to the topic types. The acronym refers to the first letter of each topic type. -In addition to the four primary topic types, we also have a page type for -[Tutorials](tutorial.md) and [Get started](#get-started). +## Other page and topic types + +In addition to the four primary topic types, you can use the following: + +- Page types: [Tutorials](tutorial.md) and [Get started](#get-started) +- Topic type: [Related topics](#related-topics) +- Page or topic type: [Glossaries](glossary.md) + +## Pages and topics to avoid + +You should avoid: + +- Pages that are exclusively links to other pages. The only exception are + top-level pages that aid with navigation. +- Topics that have one or two sentences only. In these cases: + - Incorporate the information in another topic. + - If the sentence links to another page, use a [Related topics](#related-topics) link instead. + +## Topic title guidelines + +In general, for topic titles: + +- Be clear and direct. Make every word count. +- Use articles and prepositions. +- Follow [capitalization](../styleguide/index.md#capitalization) guidelines. +- Do not repeat text from earlier topic titles. For example, if the page is about merge requests, + instead of `Troubleshooting merge requests`, use only `Troubleshooting`. + +See also [guidelines for heading levels in Markdown](../styleguide/index.md#heading-levels-in-markdown). ## Related topics If inline links are not sufficient, you can create a topic called **Related topics** and include an unordered list of related topics. This topic should be above the Troubleshooting section. +Links in this section should be brief and scannable. They are usually not +full sentences, and so should not end in a period. + ```markdown ## Related topics -- [Configure your pipeline](link-to-topic). -- [Trigger a pipeline manually](link-to-topic). +- [CI/CD variables](link-to-topic) +- [Environment variables](link-to-topic) ``` ## Get started @@ -57,22 +87,3 @@ consider using subsections for each distinct task. In the left nav, use `Get started` as the text. On the page itself, spell out the full name. For example, `Get started with application security`. - -## Topics and resources - -Some pages are solely a list of links to other documentation. - -We do not encourage this page type. Lists of links can get out-of-date quickly -and offer little value to users, who prefer to search to find information. - -## Topic title guidelines - -In general, for topic titles: - -- Be clear and direct. Make every word count. -- Use articles and prepositions. -- Follow [capitalization](../styleguide/index.md#capitalization) guidelines. -- Do not repeat text from earlier topic titles. For example, if the page is about merge requests, - instead of `Troubleshooting merge requests`, use only `Troubleshooting`. - -See also [guidelines for heading levels in Markdown](../styleguide/index.md#heading-levels-in-markdown). diff --git a/doc/development/documentation/topic_types/task.md b/doc/development/documentation/topic_types/task.md index f596ffc9b8b..2ddfd841ec3 100644 --- a/doc/development/documentation/topic_types/task.md +++ b/doc/development/documentation/topic_types/task.md @@ -155,4 +155,4 @@ how to write the phrase for each role. ## Related topics -- [View the format for writing task steps](../styleguide/index.md#navigation). +- [How to write task steps](../styleguide/index.md#navigation) diff --git a/doc/development/documentation/topic_types/tutorial.md b/doc/development/documentation/topic_types/tutorial.md index 1b1426a0465..b75b1e6b629 100644 --- a/doc/development/documentation/topic_types/tutorial.md +++ b/doc/development/documentation/topic_types/tutorial.md @@ -13,9 +13,17 @@ In general, you might consider using a tutorial when: of sub-steps. - The steps cover a variety of GitLab features or third-party tools. -Tutorials are learning aids that complement our core documentation. -They do not introduce new features. -Always use the primary [topic types](index.md) to document new features. +## Tutorial guidance + +- Tutorials are not [tasks](task.md). A task gives instructions for one procedure. + A tutorial combines multiple tasks to achieve a specific goal. +- Tutorials provide a working example. Ideally the reader can create the example the + tutorial describes. If they can't replicate it exactly, they should be able + to replicate something similar. +- Tutorials do not introduce new features. +- Tutorials do not need to adhere to the Single Source of Truth tenet. While it's not + ideal to duplicate content that is available elsewhere, it's worse to force the reader to + leave the page to find what they need. ## Tutorial format @@ -31,7 +39,9 @@ To create a website: 1. [Do the first task](#do-the-first-task) 1. [Do the second task](#do-the-second-task) -Prerequisites (optional): +## Prerequisites + +This topic is optional. - Thing 1 - Thing 2 |