| Avoid semicolons. Use two sentences instead. | _That's the way that the world goes 'round. You're up one day and the next you're down._
| 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._ |
| Avoid semicolons. Use two sentences instead. | That's the way that the world goes 'round. You're up one day and the next you're down.
| 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 _or_ in a list of three or more items. (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._ |
| When a colon is part of a sentence, always use lowercase after the colon. | _Linked issues: a way to create a relationship between issues._ |
| Use serial commas (Oxford commas) before the final **and** or **or** in a list of three or more items. (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. |
| When a colon is part of a sentence, always use lowercase after the colon. | Linked issues: a way to create a relationship between issues. |
<!-- vale gitlab.Repetition = YES -->
...
...
@@ -740,7 +740,7 @@ For other punctuation rules, refer to the
## Headings
- Add _only one H1_ in each document, by adding `#` at the beginning of
- Add only one H1 in each document, by adding `#` at the beginning of
it (when using Markdown). The `h1` becomes 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`
...
...
@@ -839,7 +839,7 @@ We include guidance for links in these categories:
### 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]` reference-style links.
It's easier to read, review, and maintain. Do not use `[Text][identifier]` reference-style links.
- 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)`,
...
...
@@ -848,7 +848,7 @@ We include guidance for links in these categories:
### Links to internal documentation
NOTE:
_Internal_ refers to documentation in the same project. When linking to
**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.
...
...
@@ -980,8 +980,8 @@ the commit link ensures the user lands on the line you're referring to. The
**Permalink** button, displayed when viewing a file in a project,
provides a link to the most recent commit of that 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).`
-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 has changed line numbers due to additional
commits, you can still search the file for that query. In this case, update the
...
...
@@ -1042,13 +1042,13 @@ they need to interact with the application.
When you take screenshots:
-_Capture the most relevant area of the page._ Don't include unnecessary white
-**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.
-**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
-**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.
...
...
@@ -1067,8 +1067,8 @@ When you take screenshots:
- 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.
- 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.
...
...
@@ -1083,7 +1083,7 @@ documentation site. For accessibility and SEO, use [descriptions](https://webaim
that:
- Are accurate, succinct, and unique.
- Don't use _image of…_ or _graphic of…_ to describe the image.
- Don't use **image of** or **graphic of** to describe the image.
### Compress images
...
...
@@ -1156,7 +1156,7 @@ embedded videos take up a lot of space on the page and can be distracting to rea
To embed a video:
1. Copy the code from this procedure 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).
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">`.
...
...
@@ -1452,17 +1452,17 @@ Use these verbs for specific uses with user interface
