summaryrefslogtreecommitdiff
path: root/doc/development/documentation/styleguide
diff options
context:
space:
mode:
Diffstat (limited to 'doc/development/documentation/styleguide')
-rw-r--r--doc/development/documentation/styleguide/index.md19
-rw-r--r--doc/development/documentation/styleguide/word_list.md29
2 files changed, 38 insertions, 10 deletions
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: