diff options
Diffstat (limited to 'doc/development/documentation/styleguide.md')
| -rw-r--r-- | doc/development/documentation/styleguide.md | 2062 |
1 files changed, 2 insertions, 2060 deletions
diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md index 6075124ef40..a12c2740083 100644 --- a/doc/development/documentation/styleguide.md +++ b/doc/development/documentation/styleguide.md @@ -1,2063 +1,5 @@ --- -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/engineering/ux/technical-writing/#designated-technical-writers -description: 'Writing styles, markup, formatting, and other standards for GitLab Documentation.' +redirect_to: 'styleguide/index.md' --- -# Documentation Style Guide - -This document defines the standards for GitLab's documentation content and -files. - -For broader information about the documentation, see the [Documentation guidelines](index.md). - -For guidelines specific to text in the GitLab interface, see the Pajamas [Content](https://design.gitlab.com/content/error-messages) section. - -For information on how to validate styles locally or by using GitLab CI/CD, see [Testing](index.md#testing). - -Use this guide for standards on grammar, formatting, word usage, and more. - -You can also view a list of [recent updates to this guide](https://gitlab.com/dashboard/merge_requests?scope=all&utf8=%E2%9C%93&state=merged&label_name[]=tw-style¬[label_name][]=docs%3A%3Afix). - -If you can't find what you need: - -- View the GitLab Handbook for [writing style guidelines](https://about.gitlab.com/handbook/communication/#writing-style-guidelines) that apply to all GitLab content. -- Refer to one of the following: - - - [Microsoft Style Guide](https://docs.microsoft.com/en-us/style-guide/). - - [Google Developer Documentation Style Guide](https://developers.google.com/style). - -If you have questions about style, mention `@tw-style` in an issue or merge request, or, if you have access to the GitLab Slack workspace, use `#docs-process`. - -## Documentation is the single source of truth (SSOT) - -### Why a single source of truth - -The documentation of GitLab products and features is the SSOT for all -information related to implementation, usage, and troubleshooting. It evolves -continuously, in keeping with new products and features, and with improvements -for clarity, accuracy, and completeness. - -This policy prevents information silos, making it easier to find information -about GitLab products. - -It also informs decisions about the kinds of content we include in our -documentation. - -### All information - -Include problem-solving actions that may address rare cases or be considered -*risky*, so long as proper context is provided in the form of fully detailed -warnings and caveats. This kind of content should be included as it could be -helpful to others and, when properly explained, its benefits outweigh the risks. -If you think you have found an exception to this rule, contact the -Technical Writing team. - -We will add all troubleshooting information to the documentation, no matter how -unlikely a user is to encounter a situation. For the [Troubleshooting sections](#troubleshooting), -people in GitLab Support can merge additions themselves. - -### All media types - -Include any media types/sources if the content is relevant to readers. You can -freely include or link presentations, diagrams, videos, and so on; no matter who -it was originally composed for, if it is helpful to any of our audiences, we can -include it. - -- If you use an image that has a separate source file (for example, a vector or - diagram format), link the image to the source file so that it may be reused or - updated by anyone. -- Do not copy and paste content from other sources unless it is a limited - quotation with the source cited. Typically it is better to either rephrase - relevant information in your own words or link out to the other source. - -### No special types - -In the software industry, it is a best practice to organize documentation in -different types. For example, [Divio recommends](https://www.divio.com/blog/documentation/): - -- Tutorials -- How-to guides -- Explanation -- Reference (for example, a glossary) - -At GitLab, we have so many product changes in our monthly releases that we can't -afford to continuously update multiple types of information. If we have multiple -types, the information will become outdated. Therefore, we have a -[single template](structure.md) for documentation. - -We currently do not distinguish specific document types, although we are open to -reconsidering this policy after the documentation has reached a future stage of -maturity and quality. If you are reading this, then despite our continuous -improvement efforts, that point hasn't been reached. - -### Link instead of summarize - -There is a temptation to summarize the information on another page. This will -cause the information to live in two places. Instead, link to the single source -of truth and explain why it is important to consume the information. - -### Organize by topic, not by type - -Beyond top-level audience-type folders (for example, `administration`), we -organize content by topic, not by type, so it can be located as easily as -possible within the single-source-of-truth (SSOT) section for the subject -matter. - -For example, do not create groupings of similar media types. For example: - -- Glossaries. -- FAQs. -- Sets of all articles or videos. - -Such grouping of content by type makes it difficult to browse for the information -you need and difficult to maintain up-to-date content. Instead, organize content -by its subject (for example, everything related to CI goes together) and -cross-link between any related content. - -### Docs-first methodology - -We employ a *documentation-first methodology* to help ensure the documentation -remains a complete and trusted resource, and to make communicating about the use -of GitLab more efficient. - -- If the answer to a question exists in documentation, share the link to the - documentation instead of rephrasing the information. -- When you encounter new information not available in GitLab’s documentation (for - example, when working on a support case or testing a feature), your first step - should be to create a merge request (MR) to add this information to the - documentation. You can then share the MR in order to communicate this - information. - -New information that would be useful toward the future usage or troubleshooting -of GitLab should not be written directly in a forum or other messaging system, -but added to a documentation MR and then referenced, as described above. Note -that among any other documentation changes, you can either: - -- Add a [Troubleshooting section](#troubleshooting) to a doc if none exists. -- Un-comment and use the placeholder Troubleshooting section included as part of - our [documentation template](structure.md#template-for-new-docs), if present. - -The more we reflexively add useful information to the documentation, the more -(and more successfully) the documentation will be used to efficiently accomplish -tasks and solve problems. - -If you have questions when considering, authoring, or editing documentation, ask -the Technical Writing team on Slack in `#docs` or in GitLab by mentioning the -writer for the applicable [DevOps stage](https://about.gitlab.com/handbook/product/product-categories/#devops-stages). -Otherwise, forge ahead with your best effort. It does not need to be perfect; -the team is happy to review and improve upon your content. Please review the -[Documentation guidelines](index.md) before you begin your first documentation MR. - -Having a knowledge base in any form that is separate from the documentation would -be against the documentation-first methodology because the content would overlap with -the documentation. - -## Markdown - -All GitLab documentation is written using [Markdown](https://en.wikipedia.org/wiki/Markdown). - -The [documentation website](https://docs.gitlab.com) uses GitLab Kramdown as its -Markdown rendering engine. For a complete Kramdown reference, see the -[GitLab Markdown Kramdown Guide](https://about.gitlab.com/handbook/markdown-guide/). - -The [`gitlab-kramdown`](https://gitlab.com/gitlab-org/gitlab_kramdown) Ruby gem -will support all [GFM markup](../../user/markdown.md) in the future. That is, -all markup supported for display in the GitLab application itself. For now, use -regular Markdown markup, following the rules in the linked style guide. - -Note that Kramdown-specific markup (for example, `{:.class}`) will not render -properly on GitLab instances under [`/help`](index.md#gitlab-help). - -### HTML in Markdown - -Hard-coded HTML is valid, although it's discouraged from being used while we -have `/help`. HTML is permitted as long as: - -- There's no equivalent markup in Markdown. -- Advanced tables are necessary. -- Special styling is required. -- Reviewed and approved by a technical writer. - -### Markdown Rules - -GitLab ensures that the Markdown used across all documentation is consistent, as -well as easy to review and maintain, by [testing documentation changes](index.md#testing) -with [markdownlint](index.md#markdownlint). This lint test fails when any -document has an issue with Markdown formatting that may cause the page to render -incorrectly within GitLab. It will also fail when a document is using -non-standard Markdown (which may render correctly, but is not the current -standard for GitLab documentation). - -#### Markdown rule `MD044/proper-names` (capitalization) - -A rule that could cause confusion is `MD044/proper-names`, as it might not be -immediately clear what caused markdownlint to fail, or how to correct the -failure. This rule checks a list of known words, listed in the `.markdownlint.json` -file in each project, to verify proper use of capitalization and backticks. -Words in backticks will be ignored by markdownlint. - -In general, product names should follow the exact capitalization of the official -names of the products, protocols, and so on. See [`.markdownlint.json`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.markdownlint.json) -for the words tested for proper capitalization in GitLab documentation. - -Some examples fail if incorrect capitalization is used: - -- MinIO (needs capital `IO`) -- NGINX (needs all capitals) -- runit (needs lowercase `r`) - -Additionally, commands, parameters, values, filenames, and so on must be -included in backticks. For example: - -- "Change the `needs` keyword in your `.gitlab.yml`..." - - `needs` is a parameter, and `.gitlab.yml` is a file, so both need backticks. - Additionally, `.gitlab.yml` will fail markdownlint without backticks as it - does not have capital G or L. -- "Run `git clone` to clone a Git repository..." - - `git clone` is a command, so it must be lowercase, while Git is the product, - so it must have a capital G. - -## Structure - -Because we want documentation to be a SSOT, we should [organize by topic, not by -type](#organize-by-topic-not-by-type). - -### 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. - -The table below shows what kind of documentation goes where. - -| Directory | What belongs here | -|:----------------------|:----------------------------------------------------------------------------------------------------------------------------------------| -| `doc/user/` | User related documentation. Anything that can be done within 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. The admin settings that can be accessed via GitLab's interface exist under `doc/user/admin_area/`. | -| `doc/api/` | API related documentation. | -| `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/` | Contains instructions for installing GitLab. | -| `doc/update/` | Contains 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 - -1. When you create a new directory, always start with an `index.md` file. - Do not use another file name 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/`. - 1. `doc/user/project/` should contain all project related documentation. - 1. `doc/user/group/` should contain all group related documentation. - 1. `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`. - 1. `doc/user/dashboard/` should contain all dashboard related documentation. - 1. `doc/user/admin_area/` should contain all admin related documentation - describing what can be achieved by accessing GitLab's admin interface - (_not to be confused with `doc/administration` where server access is - required_). - 1. 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 admin- related documentation, should be placed accordingly. -1. The `/university/` directory is *deprecated* and the majority of its documentation - has been moved. - -If you are unsure where to place a document or a content addition, this should -not stop you from authoring and contributing. You can use your best judgment and -then ask the reviewer of your MR to confirm your decision, and/or ask a -technical writer at any stage in the process. The technical writing team will -review 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-summarize) - -### References across documents - -- Give each folder an `index.md` page that introduces the topic, introduces the - pages within, and links to the pages within (including to the index pages of - any next-level subpaths). -- 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 within 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. - -- Be clear, concise, and stick to the goal of the documentation. -- Write in US English with US grammar. (Tested in [`British.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/British.yml).) -- Use [inclusive language](#inclusive-language). - -### Point of view - -In most cases, it’s appropriate to use the second-person (you, yours) point of -view, because it’s friendly and easy to understand. (Tested in -[`FirstPerson.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/FirstPerson.yml).) - -<!-- How do we harmonize the second person in Pajamas with our first person plural in our doc guide? --> - -### Capitalization - -#### Headings - -Use sentence case. For example: - -- `# Use variables to configure pipelines` -- `## Use the To-Do List` - -#### UI text - -When referring to specific user interface text, like a button label or menu -item, use the same capitalization that is displayed in the user interface. -Standards for this content are listed in the [Pajamas Design System Content section](https://design.gitlab.com/content/punctuation/) -and typically match what is called for in this Documentation Style Guide. - -If you think there is a mistake in the way the user interface text is styled, -create an issue or an MR to propose a change to the user interface text. - -#### Feature names - -- *Feature names are typically lowercase*, like those describing actions and - types of objects in GitLab. For example: - - epics - - issues - - issue weights - - merge requests - - milestones - - reorder issues - - runner, runners, shared runners - - a to-do item, to dos -- *Some features are capitalized*, typically nouns naming GitLab-specific - capabilities or tools. For example: - - GitLab CI/CD - - Repository Mirroring - - Value Stream Analytics - - the To-Do List - - the Web IDE - - Geo - - GitLab Runner (see [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/233529) for details) - -Document any exceptions in this style guide. If you're not sure, ask a GitLab -Technical Writer so that they can help decide and document the result. - -Do not match the capitalization of terms or phrases on the [Features page](https://about.gitlab.com/features/) -or [features.yml](https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/features.yml) -by default. - -#### Other terms - -Capitalize names of: - -- GitLab [product tiers](https://about.gitlab.com/pricing/). For example, - GitLab Core and GitLab Ultimate. (Tested in [`BadgeCapitalization.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/BadgeCapitalization.yml).) -- Third-party organizations, software, and products. For example, Prometheus, - Kubernetes, Git, and The Linux Foundation. -- Methods or methodologies. For example, Continuous Integration, - Continuous Deployment, Scrum, and Agile. (Tested in [`.markdownlint.json`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.markdownlint.json).) - -Follow the capitalization style listed at the [authoritative source](#links-to-external-documentation) -for the entity, which may use non-standard case styles. For example: GitLab and -npm. - -Use forms of *sign in*, instead of *log in* or *login*. For example: - -- Sign in to GitLab. -- Open the sign-in page. - -Exceptions to this rule include the concept of *single sign-on* and -references to user interface elements. For example: - -- To sign in to product X, enter your credentials, and then select **Log in**. - -### Inclusive language - -We strive to create documentation that is inclusive. This section includes -guidance and examples in the following categories: - -- [Gender-specific wording](#avoid-gender-specific-wording). - (Tested in [`InclusionGender.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionGender.yml).) -- [Ableist language](#avoid-ableist-language). - (Tested in [`InclusionAbleism.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionAbleism.yml).) -- [Cultural sensitivity](#culturally-sensitive-language). - (Tested in [`InclusionCultural.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionCultural.yml).) - -We write our developer documentation with inclusivity and diversity in mind. This -page is not an exhaustive reference, but describes some general guidelines and -examples that illustrate some best practices to follow. - -#### Avoid gender-specific wording - -When possible, use gender-neutral pronouns. For example, you can use a singular -[they](https://developers.google.com/style/pronouns#gender-neutral-pronouns) as -a gender-neutral pronoun. - -Avoid the use of gender-specific pronouns, unless referring to a specific person. - -<!-- vale gitlab.InclusionGender = NO --> - -| Use | Avoid | -|-----------------------------------|---------------------------------| -| People, humanity | Mankind | -| GitLab Team Members | Manpower | -| You can install; They can install | He can install; She can install | - -<!-- vale gitlab.InclusionGender = YES --> - -If you need to set up [Fake user information](#fake-user-information), use -diverse or non-gendered names with common surnames. - -#### Avoid ableist language - -Avoid terms that are also used in negative stereotypes for different groups. - -<!-- vale gitlab.InclusionAbleism = NO --> - -| Use | Avoid | -|------------------------|----------------------| -| Check for completeness | Sanity check | -| Uncertain outliers | Crazy outliers | -| Slows the service | Cripples the service | -| Placeholder variable | Dummy variable | -| Active/Inactive | Enabled/Disabled | -| On/Off | Enabled/Disabled | - -<!-- vale gitlab.InclusionAbleism = YES --> - -Credit: [Avoid ableist language](https://developers.google.com/style/inclusive-documentation#ableist-language) -in the Google Developer Style Guide. - -#### Culturally sensitive language - -Avoid terms that reflect negative cultural stereotypes and history. In most -cases, you can replace terms such as `master` and `slave` with terms that are -more precise and functional, such as `primary` and `secondary`. - -<!-- vale gitlab.InclusionCultural = NO --> - -| Use | Avoid | -|----------------------|-----------------------| -| Primary / secondary | Master / slave | -| Allowlist / denylist | Blacklist / whitelist | - -<!-- vale gitlab.InclusionCultural = YES --> - -For more information see the following [Internet Draft specification](https://tools.ietf.org/html/draft-knodel-terminology-02). - -### Fake user information - -You may need to include user information in entries such as a REST call or user profile. -**Do not** use real user information or email addresses in GitLab documentation. For email -addresses and names, do use: - -- **Email addresses**: Use an email address ending in `example.com`. -- **Names**: Use strings like `example_username`. Alternatively, use diverse or - non-gendered names with common surnames, such as `Sidney Jones`, `Zhang Wei`, - or `Alex Garcia`. - -### Fake URLs - -When including sample URLs in the documentation, use: - -- `example.com` when the domain name is generic. -- `gitlab.example.com` when referring to self-managed instances of GitLab. - -### Fake tokens - -There may be times where a token is needed to demonstrate an API call using -cURL or a variable used in CI. It is strongly advised not to use real tokens in -documentation even if the probability of a token being exploited is low. - -You can use the following fake tokens as examples: - -| Token type | Token value | -|:----------------------|:-------------------------------------------------------------------| -| Private user token | `<your_access_token>` | -| Personal access token | `n671WNGecHugsdEDPsyo` | -| Application ID | `2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6` | -| Application secret | `04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df` | -| CI/CD variable | `Li8j-mLUVA3eZYjPfd_H` | -| Specific runner token | `yrnZW46BrtBFqM7xDzE7dddd` | -| Shared runner token | `6Vk7ZsosqQyfreAxXTZr` | -| Trigger token | `be20d8dcc028677c931e04f3871a9b` | -| Webhook secret token | `6XhDroRcYPM5by_h-HLY` | -| Health check token | `Tu7BgjR9qeZTEyRzGG2P` | -| Request profile token | `7VgpS4Ax5utVD2esNstz` | - -### Language to avoid - -When creating documentation, limit or avoid the use of the following verb -tenses, words, and phrases: - -- Avoid jargon when possible, and when not possible, define the term or - [link to a definition](#links-to-external-documentation). -- Avoid uncommon words when a more-common alternative is possible, ensuring that - content is accessible to more readers. -- Don't write in the first person singular. - (Tested in [`FirstPerson.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/FirstPerson.yml).) - - Instead of "I" or "me," use "we," "you," "us," or "one." - - When possible, stay user focused by writing in the second person ("you" or - the imperative). -- Don't overuse "that". In many cases, you can remove "that" from a sentence - and improve readability. -- Avoid use of the future tense: - - Instead of "after you execute this command, GitLab will display the - result", use "after you execute this command, GitLab displays the result". - - Only use the future tense to convey when the action or result will actually - occur at a future time. -- Don't use slashes to clump different words together or as a replacement for - the word "or": - - Instead of "and/or," consider using "or," or use another sensible - construction. - - Other examples include "clone/fetch," author/assignee," and - "namespace/repository name." Break apart any such instances in an - appropriate way. - - Exceptions to this rule include commonly accepted technical terms, such as - CI/CD and TCP/IP. -- <!-- vale gitlab.LatinTerms = NO --> - We discourage use of Latin abbreviations, such as "e.g.," "i.e.," or "etc.," - as even native users of English might misunderstand them. - (Tested in [`LatinTerms.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/LatinTerms.yml).) - - Instead of "i.e.," use "that is." - - Instead of "e.g.," use "for example," "such as," "for instance," or "like." - - Instead of "etc.," either use "and so on" or consider editing it out, since - it can be vague. - <!-- vale gitlab.LatinTerms = YES --> -- Avoid using the word *currently* when talking about the product or its - features. The documentation describes the product as it is, and not as it - will be at some indeterminate point in the future. -- Avoid the using the word *scalability* with increasing GitLab's performance - for additional users. Using the words *scale* or *scaling* in other cases is - acceptable, but references to increasing GitLab's performance for additional - users should direct readers to the GitLab - [reference architectures](../../administration/reference_architectures/index.md) - page. -- Avoid all forms of the phrases *high availability* and *HA*, and instead - direct readers to the GitLab [reference architectures](../../administration/reference_architectures/index.md) - for information about configuring GitLab to have the performance needed for - additional users over time. -- Don't use profanity or obscenities. Doing so may negatively affect other - users and contributors, which is contrary to GitLab's value of - [Diversity, Inclusion, and Belonging](https://about.gitlab.com/handbook/values/#diversity-inclusion). -- Avoid the use of [racially-insensitive terminology or phrases](https://www.marketplace.org/2020/06/17/tech-companies-update-language-to-avoid-offensive-terms/). For example: - - Use *primary* and *secondary* for database and server relationships. - - Use *allowlist* and *denylist* to describe access control lists. -- Avoid the word *please*. For details, see [the Microsoft style guide](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/p/please). - -### Word usage clarifications - -- Don't use "may" and "might" interchangeably: - - Use "might" to indicate the probability of something occurring. "If you - skip this step, the import process might fail." - - Use "may" to indicate giving permission for someone to do something, or - consider using "can" instead. "You may select either option on this - screen." Or, "You can select either option on this screen." - -### Contractions - -Contractions are encouraged, and can create a friendly and informal tone, -especially in tutorials, instructional documentation, and -[user interfaces](https://design.gitlab.com/content/punctuation/#contractions). - -Some contractions, however, should be avoided: - -- Do not use contractions with a proper noun and a verb. For example: - - | Do | Don't | - |------------------------------------------|-----------------------------------------| - | GitLab is creating X. | GitLab's creating X. | - -- Do not use contractions when you need to emphasize a negative. For example: - - | Do | Don't | - |------------------------------------------|-----------------------------------------| - | Do *not* install X with Y. | *Don't* install X with Y. | - -- Do not use contractions in reference documentation. For example: - - | Do | Don't | - |------------------------------------------|-----------------------------------------| - | Do *not* set a limit greater than 1000. | *Don't* set a limit greater than 1000. | - | For `parameter1`, the default is 10. | For `parameter1`, the default's 10. | - -- Avoid contractions in error messages. Examples: - - | Do | Don't | - |------------------------------------------|-----------------------------------------| - | Requests to localhost are not allowed. | Requests to localhost aren't allowed. | - | Specified URL cannot be used. | Specified URL can't be used. | - -## Text - -- [Write in Markdown](#markdown). -- Splitting long lines (preferably up to 100 characters) can make it easier to - provide feedback on small chunks of text. -- Insert an empty line for new paragraphs. -- Insert an empty line between different markups (for example, after every - paragraph, header, list, and so on). Example: - - ```markdown - ## Header - - Paragraph. - - - List item 1 - - List item 2 - ``` - -### Emphasis - -- Use double asterisks (`**`) to mark a word or text in bold (`**bold**`). -- Use underscore (`_`) for text in italics (`_italic_`). -- Use greater than (`>`) for blockquotes. - -### Punctuation - -Review the general punctuation rules for the GitLab documentation in the -following table. Check specific punctuation rules for [lists](#lists) below. -Additional examples are available in the [Pajamas guide for punctuation](https://design.gitlab.com/content/punctuation/). - -| Rule | Example | -|------------------------------------------------------------------|--------------------------------------------------------| -| Always end full sentences with a period. | _For a complete overview, read through this document._ | -| Always add a space after a period when beginning a new sentence. | _For a complete overview, check this doc. For other references, check out this guide._ | -| Do not use double spaces. (Tested in [`SentenceSpacing.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/SentenceSpacing.yml).) | --- | -| Do not use tabs for indentation. Use spaces instead. You can configure your code editor to output spaces instead of tabs when pressing the tab key. | --- | -| Use serial commas ("Oxford commas") before the final 'and/or' in a list. (Tested in [`OxfordComma.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/OxfordComma.yml).) | _You can create new issues, merge requests, and milestones._ | -| Always add a space before and after dashes when using it in a sentence (for replacing a comma, for example). | _You should try this - or not._ | -| Always use lowercase after a colon. | _Related Issues: a way to create a relationship between issues._ | - -### Placeholder text - -Often in examples, a writer will provide a command or configuration that -uses values specific to the reader. - -In these cases, use [`<` and `>`](https://en.wikipedia.org/wiki/Usage_message#Pattern) -to call out where a reader must replace text with their own value. - -For example: - -```shell -cp <your_source_directory> <your_destination_directory> -``` - -### Keyboard commands - -Use the HTML `<kbd>` tag when referring to keystroke presses. For example: - -```plaintext -To stop the command, press <kbd>Ctrl</kbd>+<kbd>C</kbd>. -``` - -When the docs are generated, the output is: - -To stop the command, press <kbd>Ctrl</kbd>+<kbd>C</kbd>. - -## Lists - -- Always start list items with a capital letter, unless they are parameters or - commands that are in backticks, or similar. -- Always leave a blank line before and after a list. -- Begin a line with spaces (not tabs) to denote a [nested sub-item](#nesting-inside-a-list-item). - -### Ordered vs. unordered lists - -Only use ordered lists when their items describe a sequence of steps to follow. - -Do: - -```markdown -These are the steps to do something: - -1. First, do the first step. -1. Then, do the next step. -1. Finally, do the last step. -``` - -Don't: - -```markdown -This is a list of available features: - -1. Feature 1 -1. Feature 2 -1. Feature 3 -``` - -### Markup - -- Use dashes (`-`) for unordered lists instead of asterisks (`*`). -- Prefix `1.` to every item in an ordered list. When rendered, the list items - will appear with sequential numbering automatically. - -### Punctuation - -- Do not add commas (`,`) or semicolons (`;`) to the end of list items. -- Only add periods to the end of a list item if the item consists of a complete - sentence. The [definition of full sentence](https://www2.le.ac.uk/offices/ld/all-resources/writing/grammar/grammar-guides/sentence) - is: _"a complete sentence always contains a verb, expresses a complete idea, and makes sense standing alone"_. -- Be consistent throughout the list: if the majority of the items do not end in - a period, do not end any of the items in a period, even if they consist of a - complete sentence. The opposite is also valid: if the majority of the items - end with a period, end all with a period. -- Separate list items from explanatory text with a colon (`:`). For example: - - ```markdown - The list is as follows: - - - First item: this explains the first item. - - Second item: this explains the second item. - ``` - -**Examples:** - -Do: - -- First list item -- Second list item -- Third list item - -Don't: - -- First list item -- Second list item -- Third list item. - -Do: - -- Let's say this is a complete sentence. -- Let's say this is also a complete sentence. -- Not a complete sentence. - -Don't (vary use of periods; majority rules): - -- Let's say this is a complete sentence. -- Let's say this is also a complete sentence. -- Not a complete sentence - -### Nesting inside a list item - -It's possible to nest items under a list item, so that they render with the same -indentation as the list item. This can be done with: - -- [Code blocks](#code-blocks) -- [Blockquotes](#blockquotes) -- [Alert boxes](#alert-boxes) -- [Images](#images) - -Items nested in lists should always align with the first character of the list -item. In unordered lists (using `-`), this means two spaces for each level of -indentation: - -````markdown -- Unordered list item 1 - - A line nested using 2 spaces to align with the `U` above. - -- Unordered list item 2 - - > A quote block that will nest - > inside list item 2. - -- Unordered list item 3 - - ```plaintext - a codeblock that will next inside list item 3 - ``` - -- Unordered list item 4 - -  -```` - -For ordered lists, use three spaces for each level of indentation: - -````markdown -1. Ordered list item 1 - - A line nested using 3 spaces to align with the `O` above. - -1. Ordered list item 2 - - > A quote block that will nest - > inside list item 2. - -1. Ordered list item 3 - - ```plaintext - a codeblock that will next inside list item 3 - ``` - -1. Ordered list item 4 - -  -```` - -You can nest full lists inside other lists using the same rules as above. If you -want to mix types, that is also possible, as long as you don't mix items at the -same level: - -```markdown -1. Ordered list item one. -1. Ordered list item two. - - Nested unordered list item one. - - Nested unordered list item two. -1. Ordered list item three. - -- Unordered list item one. -- Unordered list item two. - 1. Nested ordered list item one. - 1. Nested ordered list item two. -- Unordered list item three. -``` - -## Tables - -Tables should be used to describe complex information in a straightforward -manner. Note that in many cases, an unordered list is sufficient to describe a -list of items with a single, simple description per item. But, if you have data -that is best described by a matrix, tables are the best choice for use. - -### Creation guidelines - -Due to accessibility and scannability requirements, tables should not have any -empty cells. If there is no otherwise meaningful value for a cell, consider entering -*N/A* (for 'not applicable') or *none*. - -To help tables be easier to maintain, consider adding additional spaces to the -column widths to make them consistent. For example: - -```markdown -| App name | Description | Requirements | -|:---------|:---------------------|:---------------| -| App 1 | Description text 1. | Requirements 1 | -| App 2 | Description text 2. | None | -``` - -Consider installing a plugin or extension in your editor for formatting tables: - -- [Markdown Table Prettifier](https://marketplace.visualstudio.com/items?itemName=darkriszty.markdown-table-prettify) for Visual Studio Code -- [Markdown Table Formatter](https://packagecontrol.io/packages/Markdown%20Table%20Formatter) for Sublime Text -- [Markdown Table Formatter](https://atom.io/packages/markdown-table-formatter) for Atom - -### Feature tables - -When creating tables of lists of features (such as whether or not features are -available to certain roles on the [Permissions](../../user/permissions.md#project-members-permissions) -page), use the following phrases (based on the SVG icons): - -| Option | Markdown | Displayed result | -|--------|--------------------------|------------------------| -| No | `**{dotted-circle}** No` | **{dotted-circle}** No | -| Yes | `**{check-circle}** Yes` | **{check-circle}** Yes | - -## Quotes - -Valid for Markdown content only, not for front matter entries: - -- Standard quotes: double quotes (`"`). Example: "This is wrapped in double - quotes". -- Quote within a quote: double quotes (`"`) wrap single quotes (`'`). Example: - "I am 'quoting' something within a quote". - -For other punctuation rules, please refer to the -[GitLab UX guide](https://design.gitlab.com/content/punctuation/). - -## Headings - -- Add **only one H1** in each document, by adding `#` at the beginning of - it (when using Markdown). The `h1` will be the document `<title>`. -- Start with an `h2` (`##`), and respect the order `h2` > `h3` > `h4` > `h5` > `h6`. - Never skip the hierarchy level, such as `h2` > `h4` -- Avoid putting numbers in headings. Numbers shift, hence documentation anchor - links shift too, which eventually leads to dead links. If you think it is - compelling to add numbers in headings, make sure to at least discuss it with - someone in the Merge Request. -- [Avoid using symbols and special characters](https://gitlab.com/gitlab-org/gitlab-docs/-/issues/84) - in headers. Whenever possible, they should be plain and short text. -- When possible, avoid including words that might change in the future. Changing - a heading changes its anchor URL, which affects other linked pages. -- When introducing a new document, be careful for the headings to be - grammatically and syntactically correct. Mention an [assigned technical writer (TW)](https://about.gitlab.com/handbook/product/product-categories/) - for review. - This is to ensure that no document with wrong heading is going live without an - audit, thus preventing dead links and redirection issues when corrected. -- Leave exactly one blank line before and after a heading. -- Do not use links in headings. -- Add the corresponding [product badge](#product-badges) according to the tier the - feature belongs. -- Our documentation site search engine prioritizes words used in headings and - subheadings. Make you subheading titles clear, descriptive, and complete to help - users find the right example, as shown in the section on [heading titles](#heading-titles). -- See [Capitalization](#capitalization) for guidelines on capitalizing headings. - -### Heading titles - -Keep heading titles clear and direct. Make every word count. To accommodate -search engine optimization (SEO), use the imperative, where possible. - -| Do | Don't | -|:--------------------------------------|:------------------------------------------------------------| -| Configure GDK | Configuring GDK | -| GitLab Release and Maintenance Policy | This section covers GitLab's Release and Maintenance Policy | -| Backport to older releases | Backporting to older releases | -| GitLab Pages examples | Examples | - -For guidelines on capitalizing headings, see the section on [capitalization](#capitalization). - -NOTE: **Note:** -If you change an existing title, be careful. These changes might affect not -only [links](#anchor-links) within the page, but might also affect links to the -GitLab documentation from both the GitLab application and external sites. - -### Anchor links - -Headings generate anchor links automatically when rendered. `## This is an example` -generates the anchor `#this-is-an-example`. - -NOTE: **Note:** -[Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/39717) in GitLab 13.4, [product badges](#product-badges) used in headings aren't included in the -generated anchor links. For example, when you link to -`## This is an example **(CORE)**`, use the anchor `#this-is-an-example`. - -Keep in mind that the GitLab user interface links to many documentation pages -and anchor links to take the user to the right spot. Therefore, when you change -a heading, search `doc/*`, `app/views/*`, and `ee/app/views/*` for the old -anchor to make sure you're not breaking an anchor linked from other -documentation nor from the GitLab user interface. If you find the old anchor, be -sure to replace it with the new one. - -Important: - -- Avoid crosslinking documentation to headings unless you need to link to a - specific section of the document. This will avoid breaking anchors in the - future in case the heading is changed. -- If possible, avoid changing headings since they're not only linked internally. - There are various links to GitLab documentation on the internet, such as - tutorials, presentations, StackOverflow posts, and other sources. -- Do not link to `h1` headings. - -Note that, with Kramdown, it is possible to add a custom ID to an HTML element -with Markdown markup, but they **do not** work in GitLab's `/help`. Therefore, -do not use this option until further notice. - -## Links - -Links are important in GitLab documentation. They allow you to [link instead of -summarizing](#link-instead-of-summarize) to help preserve a [single source of truth](#why-a-single-source-of-truth) -within GitLab documentation. - -We include guidance for links in the following categories: - -- How to set up [anchor links](#anchor-links) for headings. -- How to set up [criteria](#basic-link-criteria) for configuring a link. -- What to set up when [linking to a `help`](../documentation/index.md#linking-to-help) - page. -- How to set up [links to internal documentation](#links-to-internal-documentation) - for cross-references. -- How to set up [links to external documentation](#links-to-external-documentation) - for authoritative sources. -- When to use [links requiring permissions](#links-requiring-permissions). -- How to set up a [link to a video](#link-to-video). -- How to [include links with version text](#text-for-documentation-requiring-version-text). -- How to [link to specific lines of code](#link-to-specific-lines-of-code) - -### Basic link criteria - -- Use inline link Markdown markup `[Text](https://example.com)`. - It's easier to read, review, and maintain. *Do not* use `[Text][identifier]`. - -- Use [meaningful anchor texts](https://www.futurehosting.com/blog/links-should-have-meaningful-anchor-text-heres-why/). - For example, instead of writing something like `Read more about GitLab Issue Boards [here](LINK)`, - write `Read more about [GitLab Issue Boards](LINK)`. - -### Links to internal documentation - -NOTE: **Note:** -_Internal_ refers to documentation in the same project. When linking to -documentation in separate projects (for example, linking to Omnibus documentation -from GitLab documentation), you must use absolute URLs. - -Do not use absolute URLs like `https://docs.gitlab.com/ee/index.html` to -crosslink to other documentation within the same project. Use relative links to -the file, like `../index.md`. (These are converted to HTML when the site is -rendered.) - -Relative linking enables crosslinks to work: - -- in Review Apps, local previews, and `/help`. -- when working on the documentation locally, so you can verify that they work as - early as possible in the process. -- within the GitLab user interface when browsing doc files in their respective - repositories. For example, the links displayed at - `https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/README.md`. - -To link to internal documentation: - -- Use relative links to Markdown files in the same repository. -- Do not use absolute URLs or URLs from `docs.gitlab.com`. -- Use `../` to navigate to higher-level directories. -- Do not link relative to root. For example, `/ee/user/gitlab_com/index.md`. - - Don't: - - - `https://docs.gitlab.com/ee/administration/geo/replication/troubleshooting.html` - - `/ee/administration/geo/replication/troubleshooting.md` - - Do: `../../geo/replication/troubleshooting.md` - -- Always add the file name `file.md` at the end of the link with the `.md` - extension, not `.html`. - - Don't: - - - `../../merge_requests/` - - `../../issues/tags.html` - - `../../issues/tags.html#stages` - - Do: - - - `../../merge_requests/index.md` - - `../../issues/tags.md` - - `../../issues/tags.md#stages` - -NOTE: **Note:** -Using the Markdown extension is necessary for the [`/help`](index.md#gitlab-help) -section of GitLab. - -### Links to external documentation - -When describing interactions with external software, it's often helpful to -include links to external documentation. When possible, make sure that you're -linking to an [**authoritative** source](#authoritative-sources). For example, -if you're describing a feature in Microsoft's Active Directory, include a link -to official Microsoft documentation. - -### Authoritative sources - -When citing external information, use sources that are written by the people who -created the item or product in question. These sources are the most likely to be -accurate and remain up to date. - -Examples of authoritative sources include: - -- Specifications, such as a [Request for Comments](https://www.ietf.org/standards/rfcs/) - document from the Internet Engineering Task Force. -- Official documentation for a product. For example, if you're setting up an - interface with the Google OAuth 2 authorization server, include a link to - Google's documentation. -- Official documentation for a project. For example, if you're citing NodeJS - functionality, refer directly to [NodeJS documentation](https://nodejs.org/en/docs/). -- Books from an authoritative publisher. - -Examples of sources to avoid include: - -- Personal blog posts. -- Wikipedia. -- Non-trustworthy articles. -- Discussions on forums such as Stack Overflow. -- Documentation from a company that describes another company's product. - -While many of these sources to avoid can help you learn skills and or features, -they can become obsolete quickly. Nobody is obliged to maintain any of these -sites. Therefore, we should avoid using them as reference literature. - -NOTE: **Note:** -Non-authoritative sources are acceptable only if there is no equivalent -authoritative source. Even then, focus on non-authoritative sources that are -extensively cited or peer-reviewed. - -### Links requiring permissions - -Don't link directly to: - -- [Confidential issues](../../user/project/issues/confidential_issues.md). -- Project features that require [special permissions](../../user/permissions.md) - to view. - -These will fail for: - -- Those without sufficient permissions. -- Automated link checkers. - -Instead: - -- To reduce confusion, mention in the text that the information is either: - - Contained in a confidential issue. - - Requires special permission to a project to view. -- Provide a link in back ticks (`` ` ``) so that those with access to the issue - can easily navigate to it. - -Example: - -```markdown -For more information, see the [confidential issue](../../user/project/issues/confidential_issues.md) `https://gitlab.com/gitlab-org/gitlab-foss/-/issues/<issue_number>`. -``` - -### Link to specific lines of code - -When linking to specific lines within a file, link to a commit instead of to the -branch. Lines of code change through time, therefore, linking to a line by using -the commit link ensures the user lands on the line you're referring to. The -**Permalink** button, which is available when viewing a file within a project, -makes it easy to generate a link to the most recent commit of the given file. - -- *Do:* `[link to line 3](https://gitlab.com/gitlab-org/gitlab/-/blob/11f17c56d8b7f0b752562d78a4298a3a95b5ce66/.gitlab/issue_templates/Feature%20proposal.md#L3)` -- *Don't:* `[link to line 3](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/issue_templates/Feature%20proposal.md#L3).` - -If that linked expression is no longer in that line of the file due to additional -commits, you can still search the file for that query. In this case, update the -document to ensure it links to the most recent version of the file. - -## Navigation - -When documenting navigation through the user interface: - -- Use the exact wording as shown in the UI, including any capital letters as-is. -- Use bold text for navigation items and the char "greater than" (`>`) as a - separator. For example: `Navigate to your project's **Settings > CI/CD**`. -- If there are any expandable menus, make sure to mention that the user needs to - expand the tab to find the settings you're referring to. For example: - `Navigate to your project's **Settings > CI/CD** and expand **General pipelines**`. - -### Navigational elements - -Use the following terms when referring to the main GitLab user interface -elements: - -- **Top menu**: This is the top menu that spans the width of the user interface. - It includes the GitLab logo, search field, counters, and the user's avatar. -- **Left sidebar**: This is the navigation sidebar on the left of the user - interface, specific to the project or group. -- **Right sidebar**: This is the navigation sidebar on the right of the user - interface, specific to the open issue, merge request, or epic. - -## Images - -Images, including screenshots, can help a reader better understand a concept. -However, they can be hard to maintain, and should be used sparingly. - -Before including an image in the documentation, ensure it provides value to the -reader. - -### Capture the image - -Use images to help the reader understand where they are in a process, or how -they need to interact with the application. - -When you take screenshots: - -- *Capture the most relevant area of the page.* Don't include unnecessary white - space or areas of the page that don't help illustrate the point. The left - sidebar of the GitLab user interface can change, so don't include the sidebar - if it's not necessary. -- *Keep it small.* If you don't need to show the full width of the screen, don't. - A value of 1000 pixels is a good maximum width for your screenshot image. -- *Be consistent.* Coordinate screenshots with the other screenshots already on - a documentation page. For example, if other screenshots include the left - sidebar, include the sidebar in all screenshots. - -### Save the image - -- Save the image with a lowercase file name that is descriptive of the feature - or concept in the image. If the image is of the GitLab interface, append the - GitLab version to the file name, based on the following format: - `image_name_vX_Y.png`. For example, for a screenshot taken from the pipelines - page of GitLab 11.1, a valid name is `pipelines_v11_1.png`. If you're adding an - illustration that doesn't include parts of the user interface, add the release - number corresponding to the release the image was added to; for an MR added to - 11.1's milestone, a valid name for an illustration is `devops_diagram_v11_1.png`. -- Place images in a separate directory named `img/` in the same directory where - the `.md` document that you're working on is located. -- Consider using PNG images instead of JPEG. -- [Compress all PNG images](#compress-images). -- Compress gifs with <https://ezgif.com/optimize> or similar tool. -- Images should be used (only when necessary) to _illustrate_ the description - of a process, not to _replace_ it. -- Max image size: 100KB (gifs included). -- See also how to link and embed [videos](#videos) to illustrate the - documentation. - -### Add the image link to content - -The Markdown code for including an image in a document is: -`` - -The image description is the alt text for the rendered image on the -documentation site. For accessibility and SEO, use [descriptions](https://webaim.org/techniques/alttext/) -that: - -- Are accurate, succinct, and unique. -- Don't use *image of …* or *graphic of…* to describe the image. - -### Remove image shadow - -All images displayed on the [GitLab documentation site](https://docs.gitlab.com) -have a box shadow by default. To remove the box shadow, use the image class -`.image-noshadow` applied directly to an HTML `img` tag: - -```html -<img src="path/to/image.jpg" alt="Alt text (required)" class="image-noshadow"> -``` - -### Compress images - -You should always compress any new images you add to the documentation. One -known tool is [`pngquant`](https://pngquant.org/), which is cross-platform and -open source. Install it by visiting the official website and following the -instructions for your OS. - -GitLab has a [Rake task](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/tasks/pngquant.rake) -that you can use to automate the process. In the root directory of your local -copy of `https://gitlab.com/gitlab-org/gitlab`, run in a terminal: - -- Before compressing, if you want, check that all documentation PNG images have - been compressed: - - ```shell - bundle exec rake pngquant:lint - ``` - -- Compress all documentation PNG images using `pngquant`: - - ```shell - bundle exec rake pngquant:compress - ``` - -The only caveat is that the task runs on all images under `doc/`, not only the -ones you might have included in a merge request. In that case, you can run the -compress task and only commit the images that are relevant to your merge -request. - -## Videos - -Adding GitLab's existing YouTube video tutorials to the documentation is highly -encouraged, unless the video is outdated. Videos should not replace -documentation, but complement or illustrate it. If content in a video is -fundamental to a feature and its key use cases, but this is not adequately -covered in the documentation, add this detail to the documentation text or -create an issue to review the video and do so. - -Do not upload videos to the product repositories. [Link](#link-to-video) or -[embed](#embed-videos) them instead. - -### Link to video - -To link out to a video, include a YouTube icon so that readers can scan the page -for videos before reading: - -```markdown -<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For an overview, see [Video Title](link-to-video). -``` - -You can link any up-to-date video that is useful to the GitLab user. - -### Embed videos - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/472) in GitLab 12.1. - -The [GitLab documentation site](https://docs.gitlab.com) supports embedded -videos. - -You can only embed videos from [GitLab's official YouTube account](https://www.youtube.com/channel/UCnMGQ8QHMAnVIsI3xJrihhg). -For videos from other sources, [link](#link-to-video) them instead. - -In most cases, it is better to [link to video](#link-to-video) instead, because -an embed takes up a lot of space on the page and can be distracting to readers. - -To embed a video, follow the instructions below and make sure you have your MR -reviewed and approved by a technical writer. - -1. Copy the code below and paste it into your Markdown file. Leave a blank line - above and below it. Do *not* edit the code (don't remove or add any spaces). -1. In YouTube, visit the video URL you want to display. Copy the regular URL - from your browser (`https://www.youtube.com/watch?v=VIDEO-ID`) and replace - the video title and link in the line under `<div class="video-fallback">`. -1. In YouTube, select **Share**, and then select **Embed**. -1. Copy the `<iframe>` source (`src`) **URL only** - (`https://www.youtube.com/embed/VIDEO-ID`), - and paste it, replacing the content of the `src` field in the - `iframe` tag. - -```html -leave a blank line here -<div class="video-fallback"> - See the video: <a href="https://www.youtube.com/watch?v=MqL6BMOySIQ">Video title</a>. -</div> -<figure class="video-container"> - <iframe src="https://www.youtube.com/embed/MqL6BMOySIQ" frameborder="0" allowfullscreen="true"> </iframe> -</figure> -leave a blank line here -``` - -This is how it renders on the GitLab documentation site: - -<div class="video-fallback"> - See the video: <a href="https://www.youtube.com/watch?v=enMumwvLAug">What is GitLab</a>. -</div> -<figure class="video-container"> - <iframe src="https://www.youtube.com/embed/MqL6BMOySIQ" frameborder="0" allowfullscreen="true"> </iframe> -</figure> - -> Notes: -> -> - The `figure` tag is required for semantic SEO and the `video_container` -class is necessary to make sure the video is responsive and displays on -different mobile devices. -> - The `<div class="video-fallback">` is a fallback necessary for GitLab's -`/help`, as GitLab's Markdown processor does not support iframes. It's hidden on -the documentation site, but will be displayed on GitLab's `/help`. - -## Code blocks - -- Always wrap code added to a sentence in inline code blocks (`` ` ``). - For example, `.gitlab-ci.yml`, `git add .`, `CODEOWNERS`, or `only: [master]`. - File names, commands, entries, and anything that refers to code should be - added to code blocks. To make things easier for the user, always add a full - code block for things that can be useful to copy and paste, as they can easily - do it with the button on code blocks. -- HTTP methods (`HTTP POST`) and HTTP status codes, both full (`404 File Not Found`) - and abbreviated (`404`), should be wrapped in inline code blocks when used in sentences. - For example: Send a `DELETE` request to delete the runner. Send a `POST` request to create one. -- Add a blank line above and below code blocks. -- When providing a shell command and its output, prefix the shell command with `$` - and leave a blank line between the command and the output. -- When providing a command without output, don't prefix the shell command with `$`. -- If you need to include triple backticks inside a code block, use four backticks - for the codeblock fences instead of three. -- For regular fenced code blocks, always use a highlighting class corresponding to - the language for better readability. Examples: - - ````markdown - ```ruby - Ruby code - ``` - - ```javascript - JavaScript code - ``` - - ```markdown - [Markdown code example](example.md) - ``` - - ```plaintext - Code or text for which no specific highlighting class is available. - ``` - ```` - -Syntax highlighting is required for fenced code blocks added to the GitLab -documentation. Refer to the following table for the most common language classes, -or check the [complete list](https://github.com/rouge-ruby/rouge/wiki/List-of-supported-languages-and-lexers) -of available language classes: - -| Preferred language tags | Language aliases and notes | -|-------------------------|------------------------------------------------------------------------------| -| `asciidoc` | | -| `dockerfile` | Alias: `docker`. | -| `elixir` | | -| `erb` | | -| `golang` | Alias: `go`. | -| `graphql` | | -| `haml` | | -| `html` | | -| `ini` | For some simple config files that are not in TOML format. | -| `javascript` | Alias `js`. | -| `json` | | -| `markdown` | Alias: `md`. | -| `mermaid` | | -| `nginx` | | -| `perl` | | -| `php` | | -| `plaintext` | Examples with no defined language, such as output from shell commands or API calls. If a codeblock has no language, it defaults to `plaintext`. Alias: `text`. | -| `prometheus` | Prometheus configuration examples. | -| `python` | | -| `ruby` | Alias: `rb`. | -| `shell` | Aliases: `bash` or `sh`. | -| `sql` | | -| `toml` | Runner configuration examples, and other TOML-formatted configuration files. | -| `typescript` | Alias: `ts`. | -| `xml` | | -| `yaml` | Alias: `yml`. | - -For a complete reference on code blocks, see the [Kramdown guide](https://about.gitlab.com/handbook/markdown-guide/#code-blocks). - -## GitLab SVG icons - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-docs/-/issues/384) in GitLab 12.7. - -You can use icons from the [GitLab SVG library](https://gitlab-org.gitlab.io/gitlab-svgs/) -directly in the documentation. - -This way, you can achieve a consistent look when writing about interacting with -GitLab user interface elements. - -Usage examples: - -- Icon with default size (16px): `**{icon-name}**` - - Example: `**{tanuki}**` renders as: **{tanuki}**. -- Icon with custom size: `**{icon-name, size}**` - - Available sizes (in px): 8, 10, 12, 14, 16, 18, 24, 32, 48, and 72 - - Example: `**{tanuki, 24}**` renders as: **{tanuki, 24}**. -- Icon with custom size and class: `**{icon-name, size, class-name}**`. - - You can access any class available to this element in GitLab documentation CSS. - - Example with `float-right`, a - [Bootstrap utility class](https://getbootstrap.com/docs/4.4/utilities/float/): - `**{tanuki, 32, float-right}**` renders as: **{tanuki, 32, float-right}** - -### When to use icons - -Icons should be used sparingly, and only in ways that aid and do not hinder the -readability of the text. - -For example, the following adds little to the accompanying text: - -```markdown -1. Go to **{home}** **Project overview > Details** -``` - -1. Go to **{home}** **Project overview > Details** - -However, the following might help the reader connect the text to the user -interface: - -```markdown -| Section | Description | -|:-------------------------|:----------------------------------------------------------------------------------------------------------------------------| -| **{overview}** Overview | View your GitLab Dashboard, and administer projects, users, groups, jobs, runners, and Gitaly servers. | -| **{monitor}** Monitoring | View GitLab system information, and information on background jobs, logs, health checks, requests profiles, and audit logs. | -| **{messages}** Messages | Send and manage broadcast messages for your users. | -``` - -| Section | Description | -|:-------------------------|:----------------------------------------------------------------------------------------------------------------------------| -| **{overview}** Overview | View your GitLab Dashboard, and administer projects, users, groups, jobs, runners, and Gitaly servers. | -| **{monitor}** Monitoring | View GitLab system information, and information on background jobs, logs, health checks, requests profiles, and audit logs. | -| **{messages}** Messages | Send and manage broadcast messages for your users. | - -Use an icon when you find yourself having to describe an interface element. For -example: - -- Do: Select the Admin Area icon ( **{admin}** ). -- Don't: Select the Admin Area icon (the wrench icon). - -## Alert boxes - -When you need to call special attention to particular sentences, use the -following markup to create highlighted alert boxes. - -Alert boxes work for one paragraph only. Multiple paragraphs, lists, and headers -won't render correctly. For multiple lines, use [blockquotes](#blockquotes) -instead. - -Alert boxes render only on the GitLab documentation site (<https://docs.gitlab.com>). -Within GitLab itself, they will appear as plain Markdown text (like the examples -above the rendered versions, below). - -These alert boxes are used in the GitLab documentation. These aren't strict -guidelines, but for consistency you should try to use these values: - -| Color | Markup | Default keyword | Alternative keywords | -|--------|------------|-----------------|----------------------------------------------------------------------| -| Blue | `NOTE:` | `**Note:**` | | -| Yellow | `CAUTION:` | `**Caution:**` | `**Warning:**`, `**Important:**` | -| Red | `DANGER:` | `**Danger:**` | `**Warning:**`, `**Important:**`, `**Deprecated:**`, `**Required:**` | -| Green | `TIP:` | `**Tip:**` | | - -### Note - -Notes indicate additional information that is of special use to the reader. -Notes are most effective when used _sparingly_. - -Try to avoid them. Too many notes can impact the scannability of a topic and -create an overly busy page. - -Instead of adding a note, try one of these alternatives: - -- Re-write the sentence as part of the most-relevant paragraph. -- Put the information into its own standalone paragraph. -- Put the content under a new subheading that introduces the topic, which makes - it more visible. - -If you must use a note, use the following formatting: - -```markdown -NOTE: **Note:** -This is something to note. -``` - -How it renders on the GitLab documentation site: - -NOTE: **Note:** -This is something to note. - -### Tip - -```markdown -TIP: **Tip:** -This is a tip. -``` - -How it renders on the GitLab documentation site: - -TIP: **Tip:** -This is a tip. - -### Caution - -```markdown -CAUTION: **Caution:** -This is something to be cautious about. -``` - -How it renders on the GitLab documentation site: - -CAUTION: **Caution:** -This is something to be cautious about. - -### Danger - -```markdown -DANGER: **Danger:** -This is a breaking change, a bug, or something very important to note. -``` - -How it renders on the GitLab documentation site: - -DANGER: **Danger:** -This is a breaking change, a bug, or something very important to note. - -## Blockquotes - -For highlighting a text within a blue blockquote, use this format: - -```markdown -> This is a blockquote. -``` - -which renders on the [GitLab documentation site](https://docs.gitlab.com) as: - -> This is a blockquote. - -If the text spans across multiple lines it's OK to split the line. - -For multiple paragraphs, use the symbol `>` before every line: - -```markdown -> This is the first paragraph. -> -> This is the second paragraph. -> -> - This is a list item -> - Second item in the list -``` - -Which renders to: - -> This is the first paragraph. -> -> This is the second paragraph. -> -> - This is a list item -> - Second item in the list - -## Terms - -To maintain consistency through GitLab documentation, the following guides -documentation authors on agreed styles and usage of terms. - -### Merge requests (MRs) - -Merge requests allow you to exchange changes you made to source code and -collaborate with other people on the same project. You'll see this term used in -the following ways: - -- Use lowercase *merge requests* regardless of whether referring to the feature - or individual merge requests. - -As noted in the GitLab [Writing Style Guidelines](https://about.gitlab.com/handbook/communication/#writing-style-guidelines), -if you use the **MR** acronym, expand it at least once per document page. -Typically, the first use would be phrased as _merge request (MR)_ with subsequent -instances being _MR_. - -Examples: - -- "We prefer GitLab merge requests". -- "Open a merge request to fix a broken link". -- "After you open a merge request (MR), submit your MR for review and approval". - -### Describe UI elements - -The following are styles to follow when describing user interface elements in an -application: - -- For elements with a visible label, use that label in bold with matching case. - For example, `the **Cancel** button`. -- For elements with a tooltip or hover label, use that label in bold with - matching case. For example, `the **Add status emoji** button`. - -### Verbs for UI elements - -The following are recommended verbs for specific uses with user interface -elements: - -| Recommended | Used for | Replaces | -|:--------------------|:--------------------------------------|:---------------------------| -| *select* | buttons, links, menu items, dropdowns | "click, "press," "hit" | -| *select* or *clear* | checkboxes | "enable", "click", "press" | -| *expand* | expandable sections | "open" | - -### Other Verbs - -| Recommended | Used for | Replaces | -|:------------|:--------------------------------|:----------------------| -| *go to* | making a browser go to location | "navigate to", "open" | - -## GitLab versions and tiers - -Tagged and released versions of GitLab documentation are available: - -- In the [documentation archives](https://docs.gitlab.com/archives/). -- At the `/help` URL for any GitLab installation. - -The version introducing a new feature is added to the top of the topic in the -documentation to provide a link back to how the feature was developed. - -TIP: **Tip:** -Whenever you have documentation related to the `gitlab.rb` file, you're working -with a self-managed installation. The section or page is therefore likely to -apply only to self-managed instances. If so, the relevant "`TIER` ONLY" -[Product badge](#product-badges) should be included at the highest applicable -heading level. - -### Text for documentation requiring version text - -When a feature is new or updated, you can add version information as a bulleted -item in the **Version history**, or as an inline reference with related text. - -#### Version text in the **Version History** - -If all content in a section is related, add version text in a bulleted list -following the heading for the section. To render correctly, it must be on its -own line and surrounded by blank lines. - -- For features that need to declare the GitLab version that the feature was - introduced. Text similar to the following should be added immediately below - the heading as a blockquote: - - `> Introduced in GitLab 11.3.`. - -- Whenever possible, version text should have a link to the _completed_ issue, - merge request, or epic that introduced the feature. An issue is preferred over - a merge request, and a merge request is preferred over an epic. For example: - - `> [Introduced](<link-to-issue>) in GitLab 11.3.`. - -- If the feature is only available in GitLab Enterprise Edition, mention - the [paid tier](https://about.gitlab.com/handbook/marketing/product-marketing/#tiers) - the feature is available in: - - `> [Introduced](<link-to-issue>) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.3.`. - -- If listing information for multiple version as a feature evolves, add the - information to a block-quoted bullet list. For example: - - ```markdown - > - [Introduced](<link-to-issue>) in GitLab 11.3. - > - Enabled by default in GitLab 11.4. - ``` - -- If a feature is moved to another tier: - - ```markdown - > - [Introduced](<link-to-issue>) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.5. - > - [Moved](<link-to-issue>) to [GitLab Starter](https://about.gitlab.com/pricing/) in 11.8. - > - [Moved](<link-to-issue>) to GitLab Core in 12.0. - ``` - -- If a feature is deprecated, include a link to a replacement (when available): - - ```markdown - > - [Deprecated](<link-to-issue>) in GitLab 11.3. Replaced by [meaningful text](<link-to-appropriate-documentation>). - ``` - - It's also acceptable to describe the replacement in surrounding text, if - available. - - If the deprecation is not obvious in existing text, you may want to include a - warning such as: - - ```markdown - DANGER: **Deprecated:** - This feature was [deprecated](link-to-issue) in GitLab 12.3 - and replaced by [Feature name](link-to-feature-documentation). - ``` - -#### Inline version text - -If you're adding content to an existing topic, you can add version information -inline with the existing text. - -In this case, add `([introduced/deprecated](<link-to-issue>) in GitLab X.X)`. -If applicable, include the paid tier: `([introduced/deprecated](<link-to-issue>) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.4)` - -Including the issue link is encouraged, but isn't a requirement. For example: - -```markdown -The voting strategy (introduced in GitLab 13.4) requires -the primary and secondary voters to agree. -``` - -### Versions in the past or future - -When describing functionality available in past or future versions, use: - -- *Earlier*, and not *older* or *before*. -- *Later*, and not *newer* or *after*. - -For example: - -- Available in GitLab 12.3 and earlier. -- Available in GitLab 12.4 and later. -- If using GitLab 11.4 or earlier, ... -- If using GitLab 10.6 or later, ... - -### Importance of referencing GitLab versions and tiers - -Mentioning GitLab versions and tiers is important to all users and contributors -to quickly have access to the issue or merge request that introduced the change -for reference. Also, they can easily understand what features they have in their -GitLab instance and version, given that the note has some key information. - -`[Introduced](link-to-issue) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.7` -links to the issue that introduced the feature, says which GitLab tier it -belongs to, says the GitLab version that it became available in, and links to -the pricing page in case the user wants to upgrade to a paid tier to use that -feature. - -For example, if you're a regular user and you're looking at the documentation -for a feature you haven't used before, you can immediately see if that feature -is available to you or not. Alternatively, if you've been using a certain -feature for a long time and it changed in some way, it's important to be able to -determine when it changed and what's new in that feature. - -This is even more important as we don't have a perfect process for shipping -documentation. Unfortunately, we still see features without documentation, and -documentation without features. So, for now, we cannot rely 100% on the -documentation site versions. - -Over time, version text will reference a progressively older version of GitLab. -In cases where version text refers to versions of GitLab four or more major -versions back, you can consider removing the text if it's irrelevant or confusing. - -For example, if the current major version is 12.x, version text referencing -versions of GitLab 8.x and older are candidates for removal if necessary for -clearer or cleaner documentation. - -## Products and features - -Refer to the information in this section when describing products and features -within the GitLab product documentation. - -### Avoid line breaks in names - -When entering a product or feature name that includes a space (such as -GitLab Community Edition) or even other companies' products (such as -Amazon Web Services), be sure to not split the product or feature name across -lines with an inserted line break. Splitting product or feature names across -lines makes searching for these items more difficult, and can cause problems if -names change. - -For example, the following Markdown content is *not* formatted correctly: - -```markdown -When entering a product or feature name that includes a space (such as GitLab -Community Edition), don't split the product or feature name across lines. -``` - -Instead, it should appear similar to the following: - -```markdown -When entering a product or feature name that includes a space (such as -GitLab Community Edition), don't split the product or feature name across lines. -``` - -### Product badges - -When a feature is available in paid tiers, add the corresponding tier to the -header or other page element according to the feature's availability: - -| Tier in which feature is available | Tier markup | -|:-----------------------------------------------------------------------|:----------------------| -| GitLab Core and GitLab.com Free, and their higher tiers | `**(CORE)**` | -| GitLab Starter and GitLab.com Bronze, and their higher tiers | `**(STARTER)**` | -| GitLab Premium and GitLab.com Silver, and their higher tiers | `**(PREMIUM)**` | -| GitLab Ultimate and GitLab.com Gold | `**(ULTIMATE)**` | -| *Only* GitLab Core and higher tiers (no GitLab.com-based tiers) | `**(CORE ONLY)**` | -| *Only* GitLab Starter and higher tiers (no GitLab.com-based tiers) | `**(STARTER ONLY)**` | -| *Only* GitLab Premium and higher tiers (no GitLab.com-based tiers) | `**(PREMIUM ONLY)**` | -| *Only* GitLab Ultimate (no GitLab.com-based tiers) | `**(ULTIMATE ONLY)**` | -| *Only* GitLab.com Free and higher tiers (no self-managed instances) | `**(FREE ONLY)**` | -| *Only* GitLab.com Bronze and higher tiers (no self-managed instances) | `**(BRONZE ONLY)**` | -| *Only* GitLab.com Silver and higher tiers (no self-managed instances) | `**(SILVER ONLY)**` | -| *Only* GitLab.com Gold (no self-managed instances) | `**(GOLD ONLY)**` | - -For clarity, all page title headers (H1s) must be have a tier markup for the -lowest tier that has information on the documentation page. - -If sections of a page apply to higher tier levels, they can be separately -labeled with their own tier markup. - -#### Product badge display behavior - -When using the tier markup with headers, the documentation page will display the -full tier badge with the header line. - -You can also use the tier markup with paragraphs, list items, and table cells. -For these cases, the tier mention will be represented by an orange info icon -**{information}** that will display the tiers when visitors point to the icon. -For example: - -- `**(STARTER)**` displays as **(STARTER)** -- `**(STARTER ONLY)**` displays as **(STARTER ONLY)** -- `**(SILVER ONLY)**` displays as **(SILVER ONLY)** - -#### How it works - -Introduced by [!244](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/244), -the special markup `**(STARTER)**` will generate a `span` element to trigger the -badges and tooltips (`<span class="badge-trigger starter">`). When the keyword -*only* is added, the corresponding GitLab.com badge will not be displayed. - -## Specific sections - -Certain styles should be applied to specific sections. Styles for specific -sections are outlined below. - -### GitLab restart - -There are many cases that a restart/reconfigure of GitLab is required. To avoid -duplication, link to the special document that can be found in -[`doc/administration/restart_gitlab.md`](../../administration/restart_gitlab.md). -Usually the text will read like: - -```markdown -Save the file and [reconfigure GitLab](../../administration/restart_gitlab.md) -for the changes to take effect. -``` - -If the document you are editing resides in a place other than the GitLab CE/EE -`doc/` directory, instead of the relative link, use the full path: -`https://docs.gitlab.com/ee/administration/restart_gitlab.html`. Replace -`reconfigure` with `restart` where appropriate. - -### Installation guide - -**Ruby:** -In [step 2 of the installation guide](../../install/installation.md#2-ruby), -we install Ruby from source. Whenever there is a new version that needs to -be updated, remember to change it throughout the codeblock and also replace -the sha256sum (it can be found in the [downloads page](https://www.ruby-lang.org/en/downloads/) -of the Ruby website). - -### Configuration documentation for source and Omnibus installations - -GitLab currently officially supports two installation methods: installations -from source and Omnibus packages installations. - -Whenever there is a setting that is configurable for both installation methods, -prefer to document it in the CE documentation to avoid duplication. - -Configuration settings include: - -1. Settings that touch configuration files in `config/`. -1. NGINX settings and settings in `lib/support/` in general. - -When there is a list of steps to perform, usually that entails editing the -configuration file and reconfiguring/restarting GitLab. In such case, follow -the style below as a guide: - -````markdown -**For Omnibus installations** - -1. Edit `/etc/gitlab/gitlab.rb`: - - ```ruby - 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. - ---- - -**For installations from source** - -1. Edit `config/gitlab.yml`: - - ```yaml - gitlab: - host: "gitlab.example.com" - ``` - -1. Save the file and [restart](path/to/administration/restart_gitlab.md#installations-from-source) - GitLab for the changes to take effect. -```` - -In this case: - -- Before each step list the installation method is declared in bold. -- Three dashes (`---`) are used to create a horizontal line and separate the two - methods. -- The code blocks are indented one or more spaces under the list item to render - correctly. -- Different highlighting languages are used for each config in the code block. -- The [GitLab Restart](#gitlab-restart) section is used to explain a required - restart or reconfigure of GitLab. - -### Troubleshooting - -For troubleshooting sections, you should provide as much context as possible so -users can identify the problem they are facing and resolve it on their own. You -can facilitate this by making sure the troubleshooting content addresses: - -1. The problem the user needs to solve. -1. How the user can confirm they have the problem. -1. Steps the user can take towards resolution of the problem. - -If the contents of each category can be summarized in one line and a list of -steps aren't required, consider setting up a [table](#tables) with headers of -*Problem* \| *Cause* \| *Solution* (or *Workaround* if the fix is temporary), or -*Error message* \| *Solution*. - -## Feature flags - -Learn how to [document features deployed behind flags](feature_flags.md). For -guidance on developing GitLab with feature flags, see [Feature flags in development of GitLab](../feature_flags/index.md). - -## GraphQL API - -GraphQL APIs are different from [RESTful APIs](restful_api_styleguide.md). Reference -information is generated in our [GraphQL reference](../../api/graphql/reference/index.md). - -However, it's helpful to include examples on how to use GraphQL for different -*use cases*, with samples that readers can use directly in the -[GraphiQL explorer](../api_graphql_styleguide.md#graphiql). - -This section describes the steps required to add your GraphQL examples to -GitLab documentation. - -### Add a dedicated GraphQL page - -To create a dedicated GraphQL page, create a new `.md` file in the -`doc/api/graphql/` directory. Give that file a functional name, such as -`import_from_specific_location.md`. - -### Start the page with an explanation - -Include a page title that describes the GraphQL functionality in a few words, -such as: - -```markdown -# Search for [substitute kind of data] -``` - -Describe the search. One sentence may be all you need. More information may -help readers learn how to use the example for their GitLab deployments. - -### Include a procedure using the GraphiQL explorer - -The GraphiQL explorer can help readers test queries with working deployments. -Set up the section with the following: - -- Use the following title: - - ```markdown - ## Set up the GraphiQL explorer - ``` - -- Include a code block with the query that anyone can include in their - instance of the GraphiQL explorer: - - ````markdown - ```graphql - query { - <insert queries here> - } - ``` - ```` - -- Tell the user what to do: - - ```markdown - 1. Open the GraphiQL explorer tool in the following URL: `https://gitlab.com/-/graphql-explorer`. - 1. Paste the `query` listed above into the left window of your GraphiQL explorer tool. - 1. Select Play to get the result shown here: - ``` - -- Include a screenshot of the result in the GraphiQL explorer. Follow the naming - convention described in the [Save the image](#save-the-image) section. -- Follow up with an example of what you can do with the output. Make sure the - example is something that readers can do on their own deployments. -- Include a link to the [GraphQL API resources](../../api/graphql/reference/index.md). - -### Add the GraphQL example to the Table of Contents - -You'll need to open a second MR, against the [GitLab documentation repository](https://gitlab.com/gitlab-org/gitlab-docs/). - -We store our Table of Contents in the `default-nav.yaml` file, in the -`content/_data` subdirectory. You can find the GraphQL section under the -following line: - -```yaml -- category_title: GraphQL -``` - -Be aware that CI tests for that second MR will fail with a bad link until the -main MR that adds the new GraphQL page is merged. - -And that's all you need! +This document was moved to [another location](styleguide/index.md). |