Commit b835e77f authored by Achilleas Pipinellis's avatar Achilleas Pipinellis

Merge branch 'sselhorn-master-patch-11467' into 'master'

Updated punctuation guidelines to remove unnecessary text

See merge request gitlab-org/gitlab!83794
parents d204f91d 20b021f2
......@@ -349,17 +349,15 @@ Follow these guidelines for punctuation:
<!-- vale gitlab.Repetition = NO -->
| Rule | Example |
|------------------------------------------------------------------|--------------------------------------------------------|
| 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. |
| Do not use typographer's quotes. Use straight quotes instead. (Tested in [`NonStandardQuotes.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/NonStandardQuotes.yml).) | "It's the questions we can't answer that teach us the most"---Patrick Rothfuss |
- End full sentences with a period.
- Use one space between sentences.
- Do not use semicolons. Use two sentences instead.
- 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 non-breaking spaces. Use standard spaces instead. (Tested in [`lint-doc.sh`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/scripts/lint-doc.sh).)
- 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 (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).)
- Avoid dashes. Use separate sentences, or commas, instead.
- Do not use typographer's ("curly") quotes. Use straight quotes instead. (Tested in [`NonStandardQuotes.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/NonStandardQuotes.yml).)
<!-- vale gitlab.Repetition = YES -->
......@@ -403,17 +401,6 @@ Backticks are more precise than quotes. For example, in this string:
It's not clear whether the user should include the period in the string.
### Spaces between words
Use only standard spaces between words. The search engine for the documentation
website doesn't split words separated with
[non-breaking spaces](https://en.wikipedia.org/wiki/Non-breaking_space) when
indexing, and fails to create expected individual search terms. Tests that search
for certain words separated by regular spaces can't find words separated by
non-breaking spaces.
Tested in [`lint-doc.sh`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/scripts/lint-doc.sh).
## Lists
- Always start list items with a capital letter, unless they're parameters or
......@@ -421,30 +408,30 @@ Tested in [`lint-doc.sh`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/scr
- 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.
### Choose between an ordered or unordered list
Do:
Use ordered lists for a sequence of steps. For example:
```markdown
These are the steps to do something:
Follow these steps to do something.
1. First, do the first step.
1. Then, do the next step.
1. Finally, do the last step.
```
Don't:
Use an unordered lists when the steps do not need to be completed in order. For example:
```markdown
This is a list of available features:
These things are imported:
1. Feature 1
1. Feature 2
1. Feature 3
- Thing 1
- Thing 2
- Thing 3
```
You can choose to introduce either list with a colon, but you do not have to.
### Markup
- Use dashes (`-`) for unordered lists instead of asterisks (`*`).
......@@ -454,12 +441,8 @@ This is a list of available features:
### Punctuation
- Don't add commas (`,`) or semicolons (`;`) to the ends of list items.
- Only add periods to the end of a list item if the item consists of a complete
sentence (with a subject and a verb).
- 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.
- If a list item is a complete sentence (with a subject and a verb), add a period at the end.
- Majority rules. If the majority of items do not end in a period, do not end any of the items in a period.
- Separate list items from explanatory text with a colon (`:`). For example:
```markdown
......@@ -469,32 +452,6 @@ This is a list of available features:
- 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
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment