diff options
Diffstat (limited to 'doc/development/documentation')
| -rw-r--r-- | doc/development/documentation/index.md | 33 | ||||
| -rw-r--r-- | doc/development/documentation/site_architecture/deployment_process.md | 29 | ||||
| -rw-r--r-- | doc/development/documentation/site_architecture/global_nav.md | 4 | ||||
| -rw-r--r-- | doc/development/documentation/structure.md | 11 | ||||
| -rw-r--r-- | doc/development/documentation/styleguide/img/tier_badge.png | bin | 9320 -> 0 bytes | |||
| -rw-r--r-- | doc/development/documentation/styleguide/index.md | 293 | ||||
| -rw-r--r-- | doc/development/documentation/styleguide/word_list.md | 85 | ||||
| -rw-r--r-- | doc/development/documentation/topic_types/concept.md | 2 | ||||
| -rw-r--r-- | doc/development/documentation/topic_types/index.md | 13 | ||||
| -rw-r--r-- | doc/development/documentation/topic_types/task.md | 6 | ||||
| -rw-r--r-- | doc/development/documentation/versions.md | 6 | ||||
| -rw-r--r-- | doc/development/documentation/workflow.md | 64 |
12 files changed, 379 insertions, 167 deletions
diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index d52db71b633..a9f2726ea93 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -12,7 +12,7 @@ The GitLab documentation is [intended as the single source of truth (SSOT)](http In addition to this page, the following resources can help you craft and contribute to documentation: - [Style Guide](styleguide/index.md) - What belongs in the docs, language guidelines, Markdown standards to follow, links, and more. -- [Topic type template](structure.md) - Learn about the different types of topics. +- [Topic types](topic_types/index.md) - Learn about the different types of topics. - [Documentation process](workflow.md). - [Markdown Guide](../../user/markdown.md) - A reference for all Markdown syntax supported by GitLab. - [Site architecture](site_architecture/index.md) - How <https://docs.gitlab.com> is built. @@ -159,26 +159,17 @@ You can use a Rake task to update the `CODEOWNERS` file. To update the `CODEOWNERS` file: -1. Open a merge request to update - [the Rake task](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/tasks/gitlab/tw/codeowners.rake) - with the latest [TW team assignments](https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments). -1. Assign the merge request to a backend maintainer for review and merge. -1. After the MR is merged, go to the root of the `gitlab` repository. -1. Run the Rake task and save the output in a file: - - ```shell - bundle exec rake tw:codeowners > ~/Desktop/updates.md - ``` - -1. Open the file (for example, `~/Desktop/updates.md`) and copy everything - except the errors at the bottom of the file. -1. Open the [`CODEOWNERS`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/CODEOWNERS) - file and paste the lines into the `^[Documentation Pages]` section. - - WARNING: - The documentation section is not the last section of the `CODEOWNERS` file. Don't - delete data that isn't ours! - +1. Review the [TW team assignments](https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments) + in the [`codeowners.rake`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/tasks/gitlab/tw/codeowners.rake) + file. If any assignments have changed: + 1. Update the `codeowners.rake` file with the changes. + 1. Assign the merge request to a technical writing manager for review and merge. +1. After the changes to `codeowners.rake` are merged, go to the root of the `gitlab` repository. +1. Run the Rake task with this command: `bundle exec rake tw:codeowners` +1. Review the command output for any pages that need attention to + their metadata. Handle any needed changes in a separate merge request. +1. Add the changes to the CODEOWNERS file to Git: `git add .gitlab/CODEOWNERS` +1. Commit your changes to your branch, and push your branch up to `origin`. 1. Create a merge request and assign it to a technical writing manager for review. ## Move, rename, or delete a page diff --git a/doc/development/documentation/site_architecture/deployment_process.md b/doc/development/documentation/site_architecture/deployment_process.md index 18cc27adaaa..2ba69ca0987 100644 --- a/doc/development/documentation/site_architecture/deployment_process.md +++ b/doc/development/documentation/site_architecture/deployment_process.md @@ -167,30 +167,5 @@ If you do not have the Maintainer role to perform this task, ask for help in the ## Docker files -The [`dockerfiles` directory](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/dockerfiles/) contains all needed -Dockerfiles to build and deploy <https://docs.gitlab.com>. It is heavily inspired by Docker's -[Dockerfile](https://github.com/docker/docker.github.io/blob/06ed03db13895bfe867761b6fc2ad40acf6026dd/Dockerfile). - -| Dockerfile | Docker image | Description | -|:---------------------------------------------------------------------------------------------------------------------------|:------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| [`bootstrap.Dockerfile`](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/dockerfiles/bootstrap.Dockerfile) | `gitlab-docs:bootstrap` | Contains all the dependencies that are needed to build the website. If the gems are updated and `Gemfile{,.lock}` changes, the image must be rebuilt. | -| [`builder.onbuild.Dockerfile`](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/dockerfiles/builder.onbuild.Dockerfile) | `gitlab-docs:builder-onbuild` | Base image to build the docs website. It uses `ONBUILD` to perform all steps and depends on `gitlab-docs:bootstrap`. | -| [`nginx.onbuild.Dockerfile`](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/dockerfiles/nginx.onbuild.Dockerfile) | `gitlab-docs:nginx-onbuild` | Base image to use for building documentation archives. It uses `ONBUILD` to perform all required steps to copy the archive, and relies upon its parent `Dockerfile.builder.onbuild` that is invoked when building single documentation archives (see the `Dockerfile` of each branch) | -| [`archives.Dockerfile`](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/dockerfiles/archives.Dockerfile) | `gitlab-docs:archives` | Contains all the versions of the website in one archive. It copies all generated HTML files from every version in one location. | - -### How to build the images - -Although build images are built automatically via GitLab CI/CD, you can build and tag all tooling images locally: - -1. Make sure you have [Docker installed](https://docs.docker.com/get-docker/). -1. Make sure you're in the `dockerfiles/` directory of the `gitlab-docs` repository. -1. Build the images: - - ```shell - docker build -t registry.gitlab.com/gitlab-org/gitlab-docs:bootstrap -f Dockerfile.bootstrap ../ - docker build -t registry.gitlab.com/gitlab-org/gitlab-docs:builder-onbuild -f Dockerfile.builder.onbuild ../ - docker build -t registry.gitlab.com/gitlab-org/gitlab-docs:nginx-onbuild -f Dockerfile.nginx.onbuild ../ - ``` - -For each image, there's a manual job under the `images` stage in -[`.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/.gitlab-ci.yml) which can be invoked at any time. +The [`dockerfiles` directory](https://gitlab.com/gitlab-org/gitlab-docs/-/tree/main/dockerfiles) contains Dockerfiles needed +to build, test, and deploy <https://docs.gitlab.com>. diff --git a/doc/development/documentation/site_architecture/global_nav.md b/doc/development/documentation/site_architecture/global_nav.md index d95ca720119..ef6f3c0ae18 100644 --- a/doc/development/documentation/site_architecture/global_nav.md +++ b/doc/development/documentation/site_architecture/global_nav.md @@ -18,12 +18,14 @@ Global navigation is the left-most pane in the documentation. You can use the Research shows that people use Google to search for GitLab product documentation. When they land on a result, we want them to find topics nearby that are related to the content they're reading. The global nav provides this information. -At the highest level, our global nav is workflow-based. Navigation needs to help users build a mental model of how to use GitLab. +At the highest level, our global nav is **workflow-based**. Navigation needs to help users build a mental model of how to use GitLab. The levels under each of the higher workflow-based topics are the names of features. For example: **Use GitLab** (_workflow_) **> Build your application** (_workflow_) **> CI/CD** (_feature_) **> Pipelines** (_feature_) +While some older sections of the nav are alphabetical, the nav should primarily be workflow-based. + ## Choose the right words for your navigation entry Before you add an item to the left nav, choose the parts of speech you want to use. diff --git a/doc/development/documentation/structure.md b/doc/development/documentation/structure.md deleted file mode 100644 index 35a93f08f66..00000000000 --- a/doc/development/documentation/structure.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'topic_types/index.md' -remove_date: '2022-11-16' ---- - -This document was moved to [another location](topic_types/index.md). - -<!-- This redirect file can be deleted after <2022-11-16>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html -->
\ No newline at end of file diff --git a/doc/development/documentation/styleguide/img/tier_badge.png b/doc/development/documentation/styleguide/img/tier_badge.png Binary files differdeleted file mode 100644 index 5fc38e08172..00000000000 --- a/doc/development/documentation/styleguide/img/tier_badge.png +++ /dev/null diff --git a/doc/development/documentation/styleguide/index.md b/doc/development/documentation/styleguide/index.md index ef934186981..3e55b334992 100644 --- a/doc/development/documentation/styleguide/index.md +++ b/doc/development/documentation/styleguide/index.md @@ -97,7 +97,7 @@ move in this direction, so we can address these issues: information into a format that is geared toward helping others, rather than documenting how a feature was implemented. -GitLab uses these [topic types](../structure.md). +GitLab uses these [topic types](../topic_types/index.md). ### Link instead of repeating text @@ -147,7 +147,7 @@ help benefit translation. For example, we: - [since and because](word_list.md#since) - [once and after](word_list.md#once) - [it](word_list.md#it) -- Avoid [ing](word_list.md#-ing-words) words. +- Avoid [-ing](word_list.md#-ing-words) words. [The GitLab voice](#the-gitlab-voice) dictates that we write clearly and directly, and with translation in mind. [The word list](word_list.md) and our Vale rules @@ -158,7 +158,7 @@ also aid in consistency, which is important for localization. All GitLab documentation is written using [Markdown](https://en.wikipedia.org/wiki/Markdown). The [documentation website](https://docs.gitlab.com) uses [GitLab Kramdown](https://gitlab.com/gitlab-org/gitlab_kramdown), -a "flavored" Kramdown engine to render pages from Markdown to HTML. The use of Kramdown's +a "flavored" Kramdown engine to render pages from Markdown to HTML. The use of Kramdown features is limited by our linters, so, use regular Markdown and follow the rules in the linked style guide. You can't use Kramdown-specific markup (for example, `{:.class}`). @@ -345,10 +345,36 @@ Some contractions, however, should be avoided: <!-- vale gitlab.Possessive = YES --> +### Possessives + +Try to avoid using possessives (`'s`) for proper nouns, like organization or product names. + +For example, instead of `Docker's CLI`, use `the Docker CLI`. + +For details, see [the Google documentation style guide](https://developers.google.com/style/possessives#product,-feature,-and-company-names). + +### Prepositions + +Use prepositions at the end of the sentence when needed. +Dangling or stranded prepositions are fine. For example: + +- You can leave the group you're a member of. +- Share the credentials with users you want to give access to. + +These constructions are more casual than the alternatives: + +- You can leave the group of which you're a member. +- Share the credentials with users to which you want to give access. + ### Acronyms If you use an acronym, spell it out on first use on a page. You do not need to spell it out more than once on a page. -When possible, try to avoid acronyms in topic titles. + +- **Titles:** Try to avoid acronyms in topic titles, especially if the acronym is not widely used. +- **Plurals:** Try not to make acronyms plural. For example, use `YAML files`, not `YAMLs`. If you must make an acronym plural, do not use an apostrophe. For example, use `APIs`, not `API's`. +- **Possessives:** Use caution when making an acronym possessive. If possible, + write the sentence to avoid making the acronym possessive. If you must make the + acronym possessive, consider spelling out the words. ### Numbers @@ -383,8 +409,12 @@ when published. Example: ### Emphasis +<!-- vale gitlab.Spelling = NO --> + Use **bold** rather than italic to provide emphasis. GitLab uses a sans-serif font and italic text does not stand out as much as it would in a serif font. For details, see [Butterick's Practical Typography guide on bold or italic](https://practicaltypography.com/bold-or-italic.html). +<!-- vale gitlab.Spelling = YES --> + You can use italics when you are introducing a term for the first time. Otherwise, use bold. - Use double asterisks (`**`) to mark a word or text in bold (`**bold**`). @@ -700,7 +730,7 @@ Put the entire link on a single line so that [linters](../testing.md) can find i ### Links in separate repositories To link to a page in a different repository, use an absolute URL. -For example, to link from a page in the GitLab repo to the Charts repo, +For example, to link from a page in the GitLab repository to the Charts repository, use a URL like `https://docs.gitlab.com/charts/`. ### Anchor links @@ -737,6 +767,28 @@ in your merge request fails. ### Text for links +Follow these guidelines for link text. + +#### Standard text + +As much as possible, use text that follows one of these patterns: + +- `For more information, see [LINK TEXT](LINK)`. +- `To [DO THIS THING], see [LINK TEXT](LINK)` + +For example: + +- `For more information, see [merge requests](../../../user/project/merge_requests/index.md).` +- `To create a review app, see [review apps](../../../ci/review_apps/index.md).` + +You can expand on this text by using phrases like +`For more information about this feature, see...` + +Do not to use alternate phrases, like `Learn more about...` or +`To read more...`. + +#### Descriptive text rather than `here` + Use descriptive text for links, rather than words like `here` or `this page.` For example, instead of: @@ -748,6 +800,14 @@ Use: - `For more information, see [merge requests](LINK)`. +#### Links to issues + +When linking to an issue, include the issue number in the link. For example: + +- `For more information, see [issue 12345](LINK).` + +Do not use the pound sign (`issue #12345`). + ### Links to external documentation When possible, avoid links to external documentation. These links can easily become outdated, and are difficult to maintain. @@ -1382,10 +1442,12 @@ Here's some other content in tab two. For tab titles, be brief and consistent. Ensure they are parallel, and start each with a capital letter. For example: -- `Omnibus package`, `Helm chart`, `Source` +- `Linux package (Omnibus)`, `Helm chart (Kubernetes)` (when documenting configuration edits, follow the + [configuration edits guide](#configuration-documentation-for-different-installation-methods)) - `15.1 and earlier`, `15.2 and later` -See [Pajamas](https://design.gitlab.com/components/tabs/#guidelines) for details. +See [Pajamas](https://design.gitlab.com/components/tabs/#guidelines) for more +details on tabs. ## Terms @@ -1414,9 +1476,7 @@ When names change, it is more complicated to search or grep text that has line b ### Product tier badges Tier badges are displayed as orange text next to a topic title. These badges link to the GitLab -pricing page. For example: - - +pricing page. You must assign a tier badge: @@ -1436,17 +1496,17 @@ functionality is described. #### Available product tier badges -| Tier in which feature is available | Tier badge | -|:------------------------------------------------------------------------|:----------------------| -| GitLab Free self-managed and SaaS, and higher tiers | `**(FREE)**` | -| GitLab Premium self-managed and SaaS, and their higher tiers | `**(PREMIUM)**` | -| GitLab Ultimate self-managed and SaaS | `**(ULTIMATE)**` | -| Only GitLab Free self-managed and higher tiers (no SaaS-based tiers) | `**(FREE SELF)**` | -| Only GitLab Premium self-managed and higher tiers (no SaaS-based tiers) | `**(PREMIUM SELF)**` | -| Only GitLab Ultimate self-managed (no SaaS-based tiers) | `**(ULTIMATE SELF)**` | -| Only GitLab Free SaaS and higher tiers (no self-managed instances) | `**(FREE SAAS)**` | -| Only GitLab Premium SaaS and higher tiers (no self-managed instances) | `**(PREMIUM SAAS)**` | -| Only GitLab Ultimate SaaS (no self-managed instances) | `**(ULTIMATE SAAS)**` | +| Where feature is available | Tier badge | +|:-----------------------------------------------------------------------------------------|:----------------------| +| On GitLab self-managed and GitLab SaaS, available in all tiers. | `**(FREE)**` | +| On GitLab self-managed and GitLab SaaS, available in Premium and Ultimate. | `**(PREMIUM)**` | +| On GitLab self-managed and GitLab SaaS, available in Ultimate. | `**(ULTIMATE)**` | +| On GitLab self-managed, available in all tiers. Not available on GitLab SaaS. | `**(FREE SELF)**` | +| On GitLab self-managed, available in Premium and Ultimate. Not available on GitLab SaaS. | `**(PREMIUM SELF)**` | +| On GitLab self-managed, available in Ultimate. Not available on GitLab SaaS. | `**(ULTIMATE SELF)**` | +| On GitLab SaaS, available in all tiers. Not available on self-managed. | `**(FREE SAAS)**` | +| On GitLab SaaS, available in Premium and Ultimate. Not available on self-managed. | `**(PREMIUM SAAS)**` | +| On GitLab SaaS, available in Ultimate. Not available on self-managed. | `**(ULTIMATE SAAS)**` | Topics that are only for instance administrators should be badged `<TIER> SELF`. Instance administrator documentation often includes sections that mention: @@ -1487,21 +1547,35 @@ we install Ruby from source. To update the guide for a new Ruby version: - Replace the sha256sum. It's available on the [downloads page](https://www.ruby-lang.org/en/downloads/) of the Ruby website. -### Configuration documentation for source and Omnibus installations +### Configuration documentation for different installation methods -GitLab supports two installation methods: installations from source, and Omnibus -packages. Possible configuration settings include: +GitLab supports four installation methods: -- Settings that touch configuration files in `config/`. -- NGINX settings. -- Other settings in `lib/support/`. +- Linux package (Omnibus) +- Helm chart (Kubernetes) +- Docker +- Self-compiled (source) Configuration procedures can require users to edit configuration files, reconfigure -GitLab, or restart GitLab. Use these styles to document these steps, replacing -`PATH/TO` with the appropriate path: +GitLab, or restart GitLab. In this case: + +- Use [tabs](#tabs) to differentiate among the various installation methods. +- Use the installation methods names exactly as described in the previous list. +- Use them in the order described below. +- Indent the code blocks to line up with the list item they belong to. +- Use the appropriate syntax highlighting for each code block (`ruby`, `shell`, or `yaml`). +- For the YAML files, always include the parent settings. +- 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: +<!-- markdownlint-disable tabs-blank-lines --> ````markdown -**For Omnibus installations** +::Tabs + +:::TabTitle Linux package (Omnibus) 1. Edit `/etc/gitlab/gitlab.rb`: @@ -1509,32 +1583,159 @@ GitLab, or restart GitLab. Use these styles to document these steps, replacing external_url "https://gitlab.example.com" ``` -1. Save the file and [reconfigure](PATH/TO/administration/restart_gitlab.md#omnibus-gitlab-reconfigure) - GitLab for the changes to take effect. +1. Save the file and reconfigure GitLab: ---- + ```shell + sudo gitlab-ctl reconfigure + ``` + +:::TabTitle Helm chart (Kubernetes) + +1. Export the Helm values: + + ```shell + helm get values gitlab > gitlab_values.yaml + ``` + +1. Edit `gitlab_values.yaml`: + + ```yaml + global: + hosts: + gitlab: + name: gitlab.example.com + ``` + +1. Save the file and apply the new values: + + ```shell + helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab + ``` + +:::TabTitle Docker + +1. Edit `docker-compose.yml`: + + ```yaml + version: "3.6" + services: + gitlab: + environment: + GITLAB_OMNIBUS_CONFIG: | + external_url "https://gitlab.example.com" + ``` -**For installations from source** +1. Save the file and restart GitLab: -1. Edit `config/gitlab.yml`: + ```shell + docker compose up -d + ``` + +:::TabTitle Self-compiled (source) + +1. Edit `/home/git/gitlab/config/gitlab.yml`: ```yaml - gitlab: - host: "gitlab.example.com" + production: &base + gitlab: + host: "gitlab.example.com" + ``` + +1. Save the file and restart GitLab: + + ```shell + # For systems running systemd + sudo systemctl restart gitlab.target + + # For systems running SysV init + sudo service gitlab restart ``` -1. Save the file and [restart](PATH/TO/administration/restart_gitlab.md#installations-from-source) - GitLab for the changes to take effect. +::EndTabs ```` +<!-- markdownlint-enable tabs-blank-lines --> + +It renders as: + +::Tabs + +:::TabTitle Linux package (Omnibus) + +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + external_url "https://gitlab.example.com" + ``` + +1. Save the file and reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +:::TabTitle Helm chart (Kubernetes) + +1. Export the Helm values: + + ```shell + helm get values gitlab > gitlab_values.yaml + ``` + +1. Edit `gitlab_values.yaml`: + + ```yaml + global: + hosts: + gitlab: + name: gitlab.example.com + ``` + +1. Save the file and apply the new values: + + ```shell + helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab + ``` + +:::TabTitle Docker + +1. Edit `docker-compose.yml`: + + ```yaml + version: "3.6" + services: + gitlab: + environment: + GITLAB_OMNIBUS_CONFIG: | + external_url "https://gitlab.example.com" + ``` -In this case: +1. Save the file and restart GitLab: -- Bold the installation method's name. -- Separate the methods with three dashes (`---`) to create a horizontal line. -- Indent the code blocks to line up with the list item they belong to.. -- Use the appropriate syntax highlighting for each code block. -- Use the [GitLab Restart](#gitlab-restart) section to explain any required - restart or reconfigure of GitLab. + ```shell + docker compose up -d + ``` + +:::TabTitle Self-compiled (source) + +1. Edit `/home/git/gitlab/config/gitlab.yml`: + + ```yaml + production: &base + gitlab: + host: "gitlab.example.com" + ``` + +1. Save the file and restart GitLab: + + ```shell + # For systems running systemd + sudo systemctl restart gitlab.target + + # For systems running SysV init + sudo service gitlab restart + ``` + +::EndTabs ## Feature flags diff --git a/doc/development/documentation/styleguide/word_list.md b/doc/development/documentation/styleguide/word_list.md index d28972a644b..333a5521536 100644 --- a/doc/development/documentation/styleguide/word_list.md +++ b/doc/development/documentation/styleguide/word_list.md @@ -745,6 +745,11 @@ For **MB** and **GB**, follow the [Microsoft guidance](https://learn.microsoft.c Do not use first-person singular. Use **you**, **we**, or **us** instead. ([Vale](../testing.md#vale) rule: [`FirstPerson.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/FirstPerson.yml)) +## member + +When you add a [user account](#user-account) to a group or project, +the user account becomes a **member**. + ## merge requests Use lowercase for **merge requests**. If you use **MR** as the acronym, spell it out on first use. @@ -767,20 +772,41 @@ Do not use **navigate**. Use **go** instead. For example: ([Vale](../testing.md#vale) rule: [`SubstitutionSuggestions.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/SubstitutionSuggestions.yml)) -## need to, should +## need to + +Try to avoid **need to**, because it's wordy. + +For example, when a variable is **required**, +instead of **You need to set the variable**, use: + +- Set the variable. +- You must set the variable. + +When the variable is **recommended**: + +- You should set the variable. -Try to avoid **needs to**, because it's wordy. If something is recommended, use **should** instead. If something is required, use **must**. +When the variable is **optional**: + +- You can set the variable. + +## normal, normally + +Don't use **normal** to mean the usual, typical, or standard way of doing something. +Use those terms instead. Use: -- You should set the variable. (recommended) -- You must set the variable. (required) -- Set the variable. (required) +- Typically, you specify a certificate. +- Usually, you specify a certificate. +- Follow the standard Git workflow. Instead of: -- You need to set the variable. -- We recommend that you set the variable. +- Normally, you specify a certificate. +- Follow the normal Git workflow. + +([Vale](../testing.md#vale) rule: [`Normal.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/Normal.yml)) ## note that @@ -898,6 +924,15 @@ For example, you might write something like: Use lowercase for **push rules**. +## recommend, we recommend + +Instead of **we recommend**, use **you should**. We want to talk to the user the way +we would talk to a colleague, and to avoid differentiation between `we` and `them`. + +- You should set the variable. (It's recommended.) +- Set the variable. (It's required.) +- You can set the variable. (It's optional.) + ## register Use **register** instead of **sign up** when talking about creating an account. @@ -1068,6 +1103,21 @@ Do not use **slave**. Another option is **secondary**. ([Vale](../testing.md#val Use **subgroup** (no hyphen) instead of **sub-group**. ([Vale](../testing.md#vale) rule: [`SubstitutionSuggestions.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/SubstitutionSuggestions.yml)) +## subscription tier + +Do not confuse **subscription** or **subscription tier** with **[license](#license)**. +A user purchases a **subscription**. That subscription has a **tier**. + +To describe tiers: + +| Instead of | Use | +|---------------------------------|----------------------------------------| +| In the Free tier or greater | In all tiers | +| In the Free tier or higher | In all tiers | +| In the Premium tier or greater | In the Premium and Ultimate tier | +| In the Premium tier or higher | In the Premium and Ultimate tier | +| In the Premium tier or lower | In the Free and Premium tier | + ## that Do not use **that** when describing a noun. For example: @@ -1127,6 +1177,11 @@ Always follow these words with a noun. For example: - Use: **Those settings** need to be configured. (Or even better, **Configure those settings.**) - Instead of: **Those** need to be configured. +## to which, of which + +Try to avoid **to which** and **of which**, and let the preposition dangle at the end of the sentence instead. +For examples, see [Prepositions](index.md#prepositions). + ## to-do item Use lowercase and hyphenate **to-do** item. ([Vale](../testing.md#vale) rule: [`ToDo.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/ToDo.yml)) @@ -1198,18 +1253,10 @@ See also [downgrade](#downgrade) and [roll back](#roll-back). Do not use **useful**. If the user doesn't find the process to be useful, we lose their trust. ([Vale](../testing.md#vale) rule: [`Simplicity.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/Simplicity.yml)) -## user, users - -When possible, address the reader directly, instead of calling them **users**. -Use the [second person](#you-your-yours), **you**, instead. +## user account -Use: - -- You can configure a pipeline. - -Instead of: - -- Users can configure a pipeline. +You create a **user account**. The user account has an [access level](#access-level). +When you add a **user account** to a group or project, the user account becomes a **member**. ## utilize @@ -1270,7 +1317,7 @@ in present tense, active voice. ## you, your, yours -Use **you**, **your**, and **yours** instead of [**the user** and **the user's**](#user-users). +Use **you**, **your**, and **yours** instead of **the user** and **the user's**. Documentation should be from the [point of view](https://design.gitlab.com/content/voice-tone/#point-of-view) of the reader. Use: diff --git a/doc/development/documentation/topic_types/concept.md b/doc/development/documentation/topic_types/concept.md index 7be6bef4fad..e01b06c2c07 100644 --- a/doc/development/documentation/topic_types/concept.md +++ b/doc/development/documentation/topic_types/concept.md @@ -11,7 +11,7 @@ A concept introduces a single feature or concept. A concept should answer the questions: - What is this? -- Why would I use it? +- Why would you use it? Think of everything someone might want to know if they've never heard of this concept before. diff --git a/doc/development/documentation/topic_types/index.md b/doc/development/documentation/topic_types/index.md index 8e8c474ce3c..964b41303cb 100644 --- a/doc/development/documentation/topic_types/index.md +++ b/doc/development/documentation/topic_types/index.md @@ -6,20 +6,19 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Documentation topic types (CTRT) -At GitLab, we have not traditionally used types for our content. However, we are starting to -move in this direction, and we now use four primary topic types: +Each topic on a page should be one of the following topic types: - [Concept](concept.md) - [Task](task.md) - [Reference](reference.md) - [Troubleshooting](troubleshooting.md) +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 acronym refers to the first letter of each topic type. -In general, each page in the GitLab documentation contains multiple topics. -Each topic on a page should be recognizable as a specific 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). @@ -66,9 +65,9 @@ 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 text guidelines +## Topic title guidelines -In general, for topic text: +In general, for topic titles: - Be clear and direct. Make every word count. - Use articles and prepositions. diff --git a/doc/development/documentation/topic_types/task.md b/doc/development/documentation/topic_types/task.md index 78d670a16d6..0dba3e079b6 100644 --- a/doc/development/documentation/topic_types/task.md +++ b/doc/development/documentation/topic_types/task.md @@ -69,6 +69,12 @@ For example, `Create an issue when you want to track bugs or future work`. To start the task steps, use a succinct action followed by a colon. For example, `To create an issue:` +## Task prerequisites + +As a best practice, if the task requires the user to have a role other than Guest, +put the minimum role in the prerequisites. See [the Word list](../styleguide/word_list.md) for +how to write the phrase for each role. + ## Related topics - [View the format for writing task steps](../styleguide/index.md#navigation). diff --git a/doc/development/documentation/versions.md b/doc/development/documentation/versions.md index 030bdec0361..334dcd73ea5 100644 --- a/doc/development/documentation/versions.md +++ b/doc/development/documentation/versions.md @@ -46,7 +46,7 @@ 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` +- `GitLab` (or, for external projects, the name of the project) 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. @@ -203,8 +203,8 @@ 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 proposed in issue `[issue-number](LINK-TO-ISSUE)`. -- You cannot do this thing, but issue `[issue-number](LINK-TO-ISSUE)` proposes to change this behavior. +- Support for improvements is proposed in `[issue <issue_number>](LINK-TO-ISSUE)`. +- You cannot do this thing, but `[issue 12345](LINK-TO-ISSUE)` proposes to change this behavior. You can say that we plan to remove a feature. diff --git a/doc/development/documentation/workflow.md b/doc/development/documentation/workflow.md index 9d8d25607c8..2effa21b266 100644 --- a/doc/development/documentation/workflow.md +++ b/doc/development/documentation/workflow.md @@ -13,29 +13,32 @@ Anyone can contribute to the GitLab documentation! You can create a merge reques accomplish their work with GitLab. If you are working on a feature or enhancement, use the -[feature workflow process described in the GitLab Handbook](https://about.gitlab.com/handbook/product/ux/technical-writing/workflow/#for-a-product-change). +[feature workflow process described in the GitLab Handbook](https://about.gitlab.com/handbook/product/ux/technical-writing/workflow/#documentation-for-a-product-change). ## How to update the docs If you are not a GitLab team member, or do not have the Developer role for the GitLab repository, to update GitLab documentation: -1. Select an issue you'd like to work on. +1. Select an [issue](https://about.gitlab.com/handbook/product/ux/technical-writing/#community-contribution-opportunities) you'd like to work on. - You don't need an issue to open a merge request. - For a Hackathon, in the issue, in a comment, mention the person who opened the issue and ask for the issue to be assigned to you. To be fair to other contributors, if you see someone has already asked to work on the issue, choose another issue. If you are looking for issues to work on and don't see any that suit you, you can always fix [Vale](testing.md#vale) issues. 1. Go to the [GitLab repository](https://gitlab.com/gitlab-org/gitlab). -1. In the top-right, select **Fork**. Forking makes a copy of the repository on GitLab.com. -1. In your fork, find the documentation page by going to the `\doc` directory. +1. In the top right, select **Fork**. Forking makes a copy of the repository on GitLab.com. +1. In your fork, find the documentation page in the `\doc` directory. 1. If you know Git, make your changes and open a merge request. If not, follow these steps: - 1. In the top right, select **Edit**, make the changes, and **Save**. - 1. From the left menu, select **Merge requests**. + 1. On the top right, select **Edit** if it is visible. If it is not, select the down arrow (**{chevron-lg-down}**) next to **Open in Web IDE** or **Gitpod**, and select **Edit**. + 1. In the **Commit message** text box, enter a commit message. Use 3-5 words, start with a capital letter, and do not end with a period. + 1. Select **Commit changes**. + 1. On the left sidebar, select **Merge requests**. + 1. Select **New merge request**. 1. For the source branch, select your fork and branch. If you did not create a branch, select `master`. For the target branch, select the [GitLab repository](https://gitlab.com/gitlab-org/gitlab) `master` branch. - 1. For the commit message, use 3-5 words, start with a capital letter, and do not end with a period. - 1. Select **Commit changes**. A merge request opens. + 1. Select **Compare branches and continue**. A new merge request opens. 1. Select the **Documentation** template. In the description, write a brief summary of the changes and link to the related issue, if there is one. + 1. Select **Create merge request**. If you need help while working on the page, view: @@ -65,7 +68,7 @@ If you are a member of the GitLab Slack workspace, you can request help in `#doc When you author an issue or merge request, you must add these labels: -- A [type label](../contributing/issue_workflow.md#type-labels). +- A [type label](../contributing/issue_workflow.md#type-labels), either `~"type::feature"` or `~"type::maintenance"`. - A [stage label](../contributing/issue_workflow.md#stage-labels) and [group label](../contributing/issue_workflow.md#group-labels). For example, `~devops::create` and `~group::source code`. - A `~documentation` [specialization label](../contributing/issue_workflow.md#specialization-labels). @@ -75,9 +78,8 @@ A member of the Technical Writing team adds these labels: - A [documentation scoped label](../../user/project/labels.md#scoped-labels) with the `docs::` prefix. For example, `~docs::improvement`. - The [`~Technical Writing` team label](../contributing/issue_workflow.md#team-labels). -- A type label: either `~"type::feature"` or `~"type::maintenance"`. -### Reviewing and merging +## Reviewing and merging Anyone with the Maintainer role to the relevant GitLab project can merge documentation changes. Maintainers must make a good-faith effort to ensure that the content: @@ -111,13 +113,24 @@ The process involves the following: The process is reflected in the **Documentation** [merge request template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/merge_request_templates/Documentation.md). -## Other ways to help +### Before merging -If you have ideas for further documentation resources please -[create an issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Documentation) -using the Documentation template. +Ensure the following if skipping an initial Technical Writer review: + +- [Product badges](styleguide/index.md#product-tier-badges) are applied. +- The GitLab [version](versions.md) that + introduced the feature is included. +- Changes to topic titles don't affect in-app hyperlinks. +- Specific [user permissions](../../user/permissions.md) are documented. +- New documents are linked from higher-level indexes, for discoverability. +- The style guide is followed: + - For [directories and files](site_architecture/folder_structure.md). + - For [images](styleguide/index.md#images). + +Merge requests that change the location of documentation must always be reviewed by a Technical +Writer before merging. -## Post-merge reviews +### Post-merge reviews If not assigned to a Technical Writer for review prior to merging, a review must be scheduled immediately after merge by the developer or maintainer. For this, @@ -146,19 +159,8 @@ Remember: - The Technical Writer can also help decide that documentation can be merged without Technical writer review, with the review to occur soon after merge. -### Before merging - -Ensure the following if skipping an initial Technical Writer review: - -- [Product badges](styleguide/index.md#product-tier-badges) are applied. -- The GitLab [version](versions.md) that - introduced the feature is included. -- Changes to topic titles don't affect in-app hyperlinks. -- Specific [user permissions](../../user/permissions.md) are documented. -- New documents are linked from higher-level indexes, for discoverability. -- The style guide is followed: - - For [directories and files](site_architecture/folder_structure.md). - - For [images](styleguide/index.md#images). +## Other ways to help -Merge requests that change the location of documentation must always be reviewed by a Technical -Writer before merging. +If you have ideas for further documentation resources please +[create an issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Documentation) +using the Documentation template. |
