diff options
Diffstat (limited to 'doc/development/documentation/styleguide')
| -rw-r--r-- | doc/development/documentation/styleguide/index.md | 132 | ||||
| -rw-r--r-- | doc/development/documentation/styleguide/word_list.md | 66 |
2 files changed, 67 insertions, 131 deletions
diff --git a/doc/development/documentation/styleguide/index.md b/doc/development/documentation/styleguide/index.md index e57ffb90028..3e9c0177d48 100644 --- a/doc/development/documentation/styleguide/index.md +++ b/doc/development/documentation/styleguide/index.md @@ -181,115 +181,6 @@ included in backticks. For example: - `git clone` is a command, so it must be lowercase, while Git is the product, so it must have a capital G. -## Structure - -We include concept and task topic types in the same larger topic. - -In general, we have one topic that's a landing page. -Below that topic in the left nav are individual topics. Each of these include a concept -and multiple related tasks, reference, and troubleshooting topics. - -### Folder structure overview - -The documentation is separated by top-level audience folders [`user`](https://gitlab.com/gitlab-org/gitlab-foss/tree/master/doc/user), -[`administration`](https://gitlab.com/gitlab-org/gitlab-foss/tree/master/doc/administration), -and [`development`](https://gitlab.com/gitlab-org/gitlab-foss/tree/master/doc/development) -(contributing) folders. - -Beyond that, we primarily follow the structure of the GitLab user interface or -API. - -Our goal is to have a clear hierarchical structure with meaningful URLs like -`docs.gitlab.com/user/project/merge_requests/`. With this pattern, you can -immediately tell that you are navigating to user-related documentation about -Project features; specifically about Merge Requests. Our site's paths match -those of our repository, so the clear structure also makes documentation easier -to update. - -Put files for a specific product area into the related folder: - -| Directory | Contents | -|:----------------------|:------------------| -| `doc/user/` | Documentation for users. Anything that can be done in the GitLab user interface goes here, including usage of the `/admin` interface. | -| `doc/administration/` | Documentation that requires the user to have access to the server where GitLab is installed. Administrator settings in the GitLab user interface are under `doc/user/admin_area/`. | -| `doc/api/` | Documentation for the API. | -| `doc/development/` | Documentation related to the development of GitLab, whether contributing code or documentation. Related process and style guides should go here. | -| `doc/legal/` | Legal documents about contributing to GitLab. | -| `doc/install/` | Instructions for installing GitLab. | -| `doc/update/` | Instructions for updating GitLab. | -| `doc/topics/` | Indexes per topic (`doc/topics/topic_name/index.md`): all resources for that topic. | - -### Work with directories and files - -When working with directories and files: - -1. When you create a new directory, always start with an `index.md` file. - Don't use another filename and do not create `README.md` files. -1. Do not use special characters and spaces, or capital letters in file - names, directory names, branch names, and anything that generates a path. -1. When creating or renaming a file or directory and it has more than one word - in its name, use underscores (`_`) instead of spaces or dashes. For example, - proper naming would be `import_project/import_from_github.md`. This applies - to both image files and Markdown files. -1. For image files, do not exceed 100KB. -1. Do not upload video files to the product repositories. - [Link or embed videos](#videos) instead. -1. There are four main directories: `user`, `administration`, `api`, and - `development`. -1. The `doc/user/` directory has five main subdirectories: `project/`, `group/`, - `profile/`, `dashboard/` and `admin_area/`. - - `doc/user/project/` should contain all project related documentation. - - `doc/user/group/` should contain all group related documentation. - - `doc/user/profile/` should contain all profile related documentation. - Every page you would navigate under `/profile` should have its own document, - for example, `account.md`, `applications.md`, or `emails.md`. - - `doc/user/dashboard/` should contain all dashboard related documentation. - - `doc/user/admin_area/` should contain all administrator-related - documentation describing what can be achieved by accessing the GitLab - administrator interface (not to be confused with `doc/administration` where - server access is required). - - Every category under `/admin/application_settings/` should have its - own document located at `doc/user/admin_area/settings/`. For example, - the **Visibility and Access Controls** category should have a document - located at `doc/user/admin_area/settings/visibility_and_access_controls.md`. -1. The `doc/topics/` directory holds topic-related technical content. Create - `doc/topics/topic_name/subtopic_name/index.md` when subtopics become necessary. - General user and administrator documentation should be placed accordingly. -1. The `/university/` directory is *deprecated* and the majority of its documentation - has been moved. - -If you're unsure where to place a document or a content addition, this shouldn't -stop you from authoring and contributing. Use your best judgment, and then ask -the reviewer of your MR to confirm your decision. You can also ask a technical writer at -any stage in the process. The technical writing team reviews all -documentation changes, regardless, and can move content if there is a better -place for it. - -### Avoid duplication - -Do not include the same information in multiple places. -[Link to a single source of truth instead.](#link-instead-of-repeating-text) - -### References across documents - -- Give each folder an `index.md` page that introduces the topic, and both introduces - and links to the child pages, including to the index pages of - any next-level sub-paths. -- To ensure discoverability, ensure each new or renamed doc is linked from its - higher-level index page and other related pages. -- When making reference to other GitLab products and features, link to their - respective documentation, at least on first mention. -- When making reference to third-party products or technologies, link out to - their external sites, documentation, and resources. - -### Structure in documents - -- Include any and all applicable subsections as described on the - [structure and template](../structure.md) page. -- Structure content in alphabetical order in tables, lists, and so on, unless - there's a logical reason not to (for example, when mirroring the user - interface or an otherwise ordered sequence). - ## Language GitLab documentation should be clear and easy to understand. @@ -320,10 +211,11 @@ create an issue or an MR to propose a change to the user interface text. #### Feature names - Feature names are typically lowercase. -- Some features are capitalized, typically nouns that name GitLab-specific - capabilities or tools. - -See the [word list](word_list.md) for details. +- Some features require title case, typically nouns that name GitLab-specific capabilities or tools. Features requiring + title case should be: + - Added as a proper name to markdownlint [configuration](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.markdownlint.yml), + so that it can be consistently applied across all documentation. + - Added to the [word list](word_list.md). If the term is not in the word list, ask a GitLab Technical Writer for advice. @@ -1151,7 +1043,8 @@ When you take screenshots: - **Review how the image renders on the page.** Preview the image locally or use the review app in the merge request. Make sure the image isn't blurry or overwhelming. - **Be consistent.** Coordinate screenshots with the other screenshots already on - a documentation page for a consistent reading experience. + a documentation page for a consistent reading experience. Ensure your navigation theme + is **Indigo** and the syntax highlighting theme is **Light**. These are the default preferences. ### Add callouts @@ -1745,11 +1638,12 @@ If the content in a topic is not ready, use the disclaimer in the topic. ### Removing versions after each major release -Whenever a major GitLab release occurs, we remove all version references -to now-unsupported versions of GitLab. Note that this includes the removal of -specific instructions for users of non-supported GitLab versions. For example, -if GitLab versions 11.x and later are supported, special -instructions for users of GitLab 10 should be removed. +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 diff --git a/doc/development/documentation/styleguide/word_list.md b/doc/development/documentation/styleguide/word_list.md index dc3dcba0c95..2c435cdc69d 100644 --- a/doc/development/documentation/styleguide/word_list.md +++ b/doc/development/documentation/styleguide/word_list.md @@ -58,11 +58,7 @@ Capitalize these words when you refer to the UI. Otherwise use lowercase. ## administrator -Use **administrator** instead of **admin** when talking about a user's access level. -Use lowercase unless you are referring to the **Admin** access level you select in the UI. - -To view the administrator access level, in the GitLab UI, go to the Admin Area and select -**Users**. Then select **New user**. +Use **administrator access** instead of **admin** when talking about a user's access level.  @@ -71,7 +67,7 @@ An **administrator** is not a [role](#roles) or [permission](#permissions). Use: - To do this thing, you must be an administrator. -- To do this thing, you must have the administrator access level. +- To do this thing, you must have administrator access. Instead of: @@ -82,6 +78,17 @@ Instead of: Use title case **Admin Area** to refer to the area of the UI that you access when you select **Menu > Admin**. This area of the UI says **Admin Area** at the top of the page and on the menu. +## agent + +Use lowercase to refer to the [GitLab agent for Kubernetes](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent). +For example: + +- To connect your cluster to GitLab, use the GitLab agent for Kubernetes. +- Install the agent in your cluster. +- Select an agent from the list. + +Do not use title case **GitLab Agent** or **GitLab Agent for Kubernetes**. + ## allow, enable Try to avoid **allow** and **enable**, unless you are talking about security-related features. @@ -102,7 +109,7 @@ This phrasing is more active and is from the user perspective, rather than the p 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](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha-beta-ga) +You might also want to link to [this section](../../../policy/alpha-beta-support.md#alpha-features) in the handbook when writing about Alpha features. ## and/or @@ -128,7 +135,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](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha-beta-ga) +You might also want to link to [this section](../../../policy/alpha-beta-support.md#beta-features) in the handbook when writing about Beta features. ## blacklist @@ -194,6 +201,10 @@ CI/CD is always uppercase. No need to spell it out on first use. 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). +## CI/CD tunnel + +Use lowercase for **tunnel** in **CI/CD tunnel**. + ## click Do not use **click**. Instead, use **select** with buttons, links, menu items, and lists. @@ -312,6 +323,11 @@ Instead of: Use **expand** instead of **open** when you are talking about expanding or collapsing a section in the UI. +## FAQ + +We want users to find information quickly, and they rarely search for the term **FAQ**. +Information in FAQs belongs with other similar information, under an easily searchable topic title. + ## field Use **box** instead of **field** or **text box**. @@ -367,6 +383,11 @@ Use title case for **GitLab Runner**. This is the product you install. See also Use **GitLab self-managed** to refer to the product license for GitLab instances managed by customers themselves. +## guide + +We want to speak directly to users. On `docs.gitlab.com`, do not use **guide** as part of a page title. +For example, **Snowplow Guide**. Instead, speak about the feature itself, and how to use it. For example, **Use Snowplow to do xyz**. + ## Guest When writing about the Guest role: @@ -540,6 +561,8 @@ Do not use **navigate**. Use **go** instead. For example: - Go to this webpage. - Open a terminal and go to the `runner` directory. +([Vale](../testing.md#vale) rule: [`SubstitutionSuggestions.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/SubstitutionSuggestions.yml)) + ## need to, should Try to avoid **needs to**, because it's wordy. Avoid **should** when you can be more specific. If something is required, use **must**. @@ -658,10 +681,22 @@ Use **press** when talking about keyboard keys. For example: Do not use profanity. Doing so may negatively affect other users and contributors, which is contrary to the GitLab value of [Diversity, Inclusion, and Belonging](https://about.gitlab.com/handbook/values/#diversity-inclusion). +## provision + +Use the term **provision** when referring to provisioning cloud infrastructure. You provision the infrastructure, and then deploy applications to it. + +For example, you might write something like: + +- Provision an AWS EKS cluster and deploy your application to it. + ## push rules Use lowercase for **push rules**. +## register + +Use **register** instead of **sign up** when talking about creating an account. + ## Reporter When writing about the Reporter role: @@ -690,6 +725,9 @@ Roles are not the same as [**access levels**](#access-level). Use lowercase for **runners**. These are the agents that run CI/CD jobs. See also [GitLab Runner](#gitlab-runner) and [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/233529). +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**. + ## (s) Do not use **(s)** to make a word optionally plural. It can slow down comprehension. For example: @@ -735,6 +773,10 @@ Instead of: Use **select** with buttons, links, menu items, and lists. **Select** applies to more devices, while **click** is more specific to a mouse. +## self-managed + +Use **self-managed** to refer to a customer's installation of GitLab. Do not use **self-hosted**. + ## Service Desk Use title case for **Service Desk**. @@ -752,6 +794,10 @@ Use **sign in** instead of **sign on** or **log on** or **log in**. If the user You can use **single sign-on**. +## sign up + +Use **register** instead of **sign up** when talking about creating an account. + ## simply, simple Do not use **simply** or **simple**. If the user doesn't find the process to be simple, we lose their trust. ([Vale](../testing.md#vale) rule: [`Simplicity.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/Simplicity.yml)) @@ -883,10 +929,6 @@ Instead of: Do not use **utilize**. Use **use** instead. It's more succinct and easier for non-native English speakers to understand. ([Vale](../testing.md#vale) rule: [`SubstitutionSuggestions.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/SubstitutionSuggestions.yml)) -## Value Stream Analytics - -Use title case for **Value Stream Analytics**. - ## via Do not use Latin abbreviations. Use **with**, **through**, or **by using** instead. ([Vale](../testing.md#vale) rule: [`LatinTerms.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/LatinTerms.yml)) |