diff options
Diffstat (limited to 'doc/development/documentation')
| -rw-r--r-- | doc/development/documentation/index.md | 2 | ||||
| -rw-r--r-- | doc/development/documentation/styleguide/index.md | 19 | ||||
| -rw-r--r-- | doc/development/documentation/styleguide/word_list.md | 29 | ||||
| -rw-r--r-- | doc/development/documentation/testing.md | 22 | ||||
| -rw-r--r-- | doc/development/documentation/topic_types/concept.md | 15 | ||||
| -rw-r--r-- | doc/development/documentation/topic_types/index.md | 2 | ||||
| -rw-r--r-- | doc/development/documentation/workflow.md | 2 |
7 files changed, 62 insertions, 29 deletions
diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index a9f2726ea93..8a5a993d913 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -241,7 +241,7 @@ with the following conventions: - It omits the `.md` extension. - It doesn't end with a forward slash (`/`). -The help text follows the [Pajamas guidelines](https://design.gitlab.com/usability/helping-users/#formatting-help-content). +The help text follows the [Pajamas guidelines](https://design.gitlab.com/usability/contextual-help#formatting-help-content). #### Linking to `/help` in HAML diff --git a/doc/development/documentation/styleguide/index.md b/doc/development/documentation/styleguide/index.md index 3e55b334992..921bb13721b 100644 --- a/doc/development/documentation/styleguide/index.md +++ b/doc/development/documentation/styleguide/index.md @@ -17,7 +17,7 @@ In addition to this page, the following resources can help you craft and contrib - [Doc contribution guidelines](../index.md) - [Recommended word list](word_list.md) - [Doc style and consistency testing](../testing.md) -- [Guidelines for UI error messages](https://design.gitlab.com/content/error-messages/) +- [Guidelines for UI error messages](https://design.gitlab.com/content/voice-and-tone#clear-error-messages) - [Documentation global navigation](../site_architecture/global_nav.md) - [GitLab Handbook style guidelines](https://about.gitlab.com/handbook/communication/#writing-style-guidelines) - [Microsoft Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/) @@ -523,10 +523,10 @@ When using code block style: ## Lists -- Use a period after every sentence, including those that complete an introductory phrase. - Do not use semicolons or commas. -- Majority rules. Use either full sentences or all fragments. Avoid a mix. -- Always start list items with a capital letter. +- Do not use a period if the phrase is not a full sentence. +- Use a period after every sentence. Do not use semicolons or commas. +- Majority rules. All items should have the same punctuation. +- Start list items with a capital letter. - Separate the introductory phrase from explanatory text with a colon (`:`). For example: ```markdown @@ -1217,7 +1217,7 @@ To embed a video: 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`), + (`https://www.youtube-nocookie.com/embed/VIDEO-ID`), and paste it, replacing the content of the `src` field in the `iframe` tag. @@ -1227,7 +1227,7 @@ leave a blank line here 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> + <iframe src="https://www.youtube-nocookie.com/embed/MqL6BMOySIQ" frameborder="0" allowfullscreen> </iframe> </figure> leave a blank line here ``` @@ -1238,7 +1238,7 @@ This is how it renders on the GitLab documentation site: 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> + <iframe src="https://www.youtube-nocookie.com/embed/MqL6BMOySIQ" frameborder="0" allowfullscreen> </iframe> </figure> > Notes: @@ -1249,6 +1249,7 @@ different mobile devices. > - The `<div class="video-fallback">` is a fallback necessary for `/help`, because the GitLab Markdown processor doesn't support iframes. It's hidden on the documentation site, but is displayed by `/help`. +> - The `www.youtube-nocookie.com` domain enables the [Privacy Enhanced Mode](https://support.google.com/youtube/answer/171780?hl=en#zippy=%2Cturn-on-privacy-enhanced-mode) of the YouTube embedded player. This mode allows users with resticted cookie preferences to view embedded videos. ## Alert boxes @@ -1446,6 +1447,8 @@ For example: [configuration edits guide](#configuration-documentation-for-different-installation-methods)) - `15.1 and earlier`, `15.2 and later` +Until we implement automated testing for broken links to tabs ([Issue 1355](https://gitlab.com/gitlab-org/gitlab-docs/-/issues/1355)), do not link directly to a single tab, even though they do have unique URL parameters. + See [Pajamas](https://design.gitlab.com/components/tabs/#guidelines) for more details on tabs. diff --git a/doc/development/documentation/styleguide/word_list.md b/doc/development/documentation/styleguide/word_list.md index 333a5521536..fcebe3b3649 100644 --- a/doc/development/documentation/styleguide/word_list.md +++ b/doc/development/documentation/styleguide/word_list.md @@ -186,6 +186,10 @@ Instead, use **assign**. For example: - Assign the issue to an epic. - Assign a user to the issue. +## authenticated user + +Use **authenticated user** instead of other variations, like **signed in user** or **logged in user**. + ## below Try to avoid **below** when referring to an example or table in a documentation page. If required, use **following** instead. For example: @@ -309,6 +313,13 @@ Users can set the default branch by using a UI setting. For examples that use the default branch, use `main` instead of [`master`](#master). +## delete + +Use **delete** when an object is completely deleted. **Delete** is the opposite of **create**. + +When the object continues to exist, use [**remove**](#remove) instead. +For example, you can remove an issue from an epic, but the issue still exists. + ## Dependency Proxy Use title case for the GitLab Dependency Proxy. @@ -487,7 +498,7 @@ Use title case for **Geo**. ## GitLab -Do not make **GitLab** possessive (GitLab's). This guidance follows [GitLab Trademark Guidelines](https://about.gitlab.com/handbook/marketing/corporate-marketing/brand-activation/trademark-guidelines/). +Do not make **GitLab** possessive (GitLab's). This guidance follows [GitLab Trademark Guidelines](https://about.gitlab.com/handbook/marketing/brand-and-product-marketing/brand/brand-activation/trademark-guidelines/). ## GitLab.com @@ -691,6 +702,10 @@ Do not use **limitations**. Use **known issues** instead. Do not use **log in** or **log on**. Use [sign in](#sign-in) instead. If the user interface has **Log in**, you can use it. +## logged-in user, logged in user + +Use **authenticated user** instead of **logged-in user** or **logged in user**. + ## lower Do not use **lower** when talking about version numbers. @@ -937,6 +952,12 @@ we would talk to a colleague, and to avoid differentiation between `we` and `the Use **register** instead of **sign up** when talking about creating an account. +## remove + +Use **remove** when an object continues to exist. For example, you can remove an issue from an epic, but the issue still exists. + +When an object is completely deleted, use [**delete**](#delete) instead. + ## Reporter When writing about the Reporter role: @@ -1075,6 +1096,10 @@ You can use **single sign-on**. Use **register** instead of **sign up** when talking about creating an account. +## signed-in user, signed in user + +Use **authenticated user** instead of **signed-in user** or **signed in user**. + ## 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)) @@ -1318,7 +1343,7 @@ in present tense, active voice. ## you, your, yours Use **you**, **your**, and **yours** instead of **the user** and **the user's**. -Documentation should be from the [point of view](https://design.gitlab.com/content/voice-tone/#point-of-view) of the reader. +Documentation should be from the [point of view](https://design.gitlab.com/content/voice-and-tone#point-of-view) of the reader. Use: diff --git a/doc/development/documentation/testing.md b/doc/development/documentation/testing.md index 8b8f281d7c1..58584b5168b 100644 --- a/doc/development/documentation/testing.md +++ b/doc/development/documentation/testing.md @@ -282,16 +282,16 @@ Vale returns three types of results: - **Error** - For branding guidelines, trademark guidelines, and anything that causes content on the docs site to render incorrectly. -- **Warning** - For Technical Writing team style preferences. -- **Suggestion** - For basic technical writing tenets and best practices. +- **Warning** - For general style guide rules, tenets, and best practices. +- **Suggestion** - For technical writing style preferences that may require refactoring of documentation or updates to an exceptions list. The result types have these attributes: -| Result type | Displayed in CI/CD job output | Causes CI/CD jobs to fail | Vale rule link | -|--------------|-------------------------------|---------------------------|----------------| -| `error` | **{check-circle}** Yes | **{check-circle}** Yes | [Error-level Vale rules](https://gitlab.com/search?utf8=✓&snippets=false&scope=&repository_ref=master&search=path%3Adoc%2F.vale%2Fgitlab+Error%3A&group_id=9970&project_id=278964) | -| `warning` | **{dotted-circle}** No | **{dotted-circle}** No | [Warning-level Vale rules](https://gitlab.com/search?utf8=✓&snippets=false&scope=&repository_ref=master&search=path%3Adoc%2F.vale%2Fgitlab+Warning%3A&group_id=9970&project_id=278964) | -| `suggestion` | **{dotted-circle}** No | **{dotted-circle}** No | [Suggestion-level Vale rules](https://gitlab.com/search?utf8=✓&snippets=false&scope=&repository_ref=master&search=path%3Adoc%2F.vale%2Fgitlab+Suggestion%3A&group_id=9970&project_id=278964) | +| Result type | Displays in CI/CD job output | Displays in MR diff | Causes CI/CD jobs to fail | Vale rule link | +|--------------|------------------------------|---------------------|---------------------------|----------------| +| `error` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | [Error-level Vale rules](https://gitlab.com/search?utf8=✓&snippets=false&scope=&repository_ref=master&search=path%3Adoc%2F.vale%2Fgitlab+Error%3A&group_id=9970&project_id=278964) | +| `warning` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | [Warning-level Vale rules](https://gitlab.com/search?utf8=✓&snippets=false&scope=&repository_ref=master&search=path%3Adoc%2F.vale%2Fgitlab+Warning%3A&group_id=9970&project_id=278964) | +| `suggestion` | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | [Suggestion-level Vale rules](https://gitlab.com/search?utf8=✓&snippets=false&scope=&repository_ref=master&search=path%3Adoc%2F.vale%2Fgitlab+Suggestion%3A&group_id=9970&project_id=278964) | #### Vale spelling test @@ -360,6 +360,10 @@ In general, follow these guidelines: If the rule is too subjective, it cannot be adequately enforced and creates unnecessary additional warnings. + - Whether it's appropriate to display in the merge request diff in the GitLab UI. + If the rule is difficult to implement directly in the merge request (for example, + it requires page refactoring), set it to suggestion-level so it displays in local editors only. + ### Install linters At a minimum, install [markdownlint](#markdownlint) and [Vale](#vale) to match the checks run in @@ -407,15 +411,13 @@ To configure markdownlint in your editor, install one of the following as approp - Sublime Text [`SublimeLinter-contrib-markdownlint` package](https://packagecontrol.io/packages/SublimeLinter-contrib-markdownlint). - Visual Studio Code [`DavidAnson.vscode-markdownlint` extension](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint). -- Atom [`linter-node-markdownlint` package](https://atom.io/packages/linter-node-markdownlint). - Vim [ALE plugin](https://github.com/dense-analysis/ale). To configure Vale in your editor, install one of the following as appropriate: -- Sublime Text [`SublimeLinter-contrib-vale` package](https://packagecontrol.io/packages/SublimeLinter-contrib-vale). +- Sublime Text [`SublimeLinter-vale` package](https://packagecontrol.io/packages/SublimeLinter-vale). - Visual Studio Code [`errata-ai.vale-server` extension](https://marketplace.visualstudio.com/items?itemName=errata-ai.vale-server). You can configure the plugin to [display only a subset of alerts](#show-subset-of-vale-alerts). -- Atom [`atomic-vale` package](https://atom.io/packages/atomic-vale). - Vim [ALE plugin](https://github.com/dense-analysis/ale). - JetBrains IDEs - No plugin exists, but [this issue comment](https://github.com/errata-ai/vale-server/issues/39#issuecomment-751714451) diff --git a/doc/development/documentation/topic_types/concept.md b/doc/development/documentation/topic_types/concept.md index e01b06c2c07..66af8780b9b 100644 --- a/doc/development/documentation/topic_types/concept.md +++ b/doc/development/documentation/topic_types/concept.md @@ -10,8 +10,8 @@ A concept introduces a single feature or concept. A concept should answer the questions: -- What is this? -- Why would you use it? +- **What** is this? +- **Why** would you use it? Think of everything someone might want to know if they've never heard of this concept before. @@ -24,12 +24,15 @@ Concepts should be in this format: ```markdown # Title (a noun, like "Widgets") -A paragraph that explains what this thing is. +A paragraph or two that explains what this thing is and why you would use it. -Another paragraph that explains what this thing is. +If you start to describe another concept, stop yourself. +Each concept should be about **one concept only**. -Remember, if you start to describe about another concept, stop yourself. -Each concept should be about one concept only. +If you start to describe **how to use the thing**, stop yourself. +Task topics explain how to use something, not concept topics. + +Do not include links to related tasks. The navigation provides links to tasks. ``` ## Concept topic titles diff --git a/doc/development/documentation/topic_types/index.md b/doc/development/documentation/topic_types/index.md index 964b41303cb..cfc231c268a 100644 --- a/doc/development/documentation/topic_types/index.md +++ b/doc/development/documentation/topic_types/index.md @@ -28,7 +28,7 @@ If inline links are not sufficient, you can create a topic called **Related topi and include an unordered list of related topics. This topic should be above the Troubleshooting section. ```markdown -# Related topics +## Related topics - [Configure your pipeline](link-to-topic). - [Trigger a pipeline manually](link-to-topic). diff --git a/doc/development/documentation/workflow.md b/doc/development/documentation/workflow.md index 2effa21b266..3c73030aceb 100644 --- a/doc/development/documentation/workflow.md +++ b/doc/development/documentation/workflow.md @@ -21,7 +21,7 @@ If you are not a GitLab team member, or do not have the Developer role for the G 1. Select an [issue](https://about.gitlab.com/handbook/product/ux/technical-writing/#community-contribution-opportunities) you'd like to work on. - You don't need an issue to open a merge request. - - For a Hackathon, in the issue, in a comment, mention the person who opened the issue and ask for the issue to be assigned to you. + - For a Hackathon, mention `@docs-hackathon` in a comment and ask for the issue to be assigned to you. To be fair to other contributors, if you see someone has already asked to work on the issue, choose another issue. If you are looking for issues to work on and don't see any that suit you, you can always fix [Vale](testing.md#vale) issues. 1. Go to the [GitLab repository](https://gitlab.com/gitlab-org/gitlab). |