summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorEvan Read <eread@gitlab.com>2019-09-10 07:35:41 +0000
committerEvan Read <eread@gitlab.com>2019-09-10 07:35:41 +0000
commit7eda144e3e6557b7f42d02a1eeff157d580ca9d1 (patch)
tree56a8f45b0399060eb4f65757322824073d95c6e5
parent200fd742fb11d1541f43898674dd27a1e70e47c3 (diff)
parent88d66248d0cfec9b03b7b2e8b86530aa4c832751 (diff)
downloadgitlab-ce-7eda144e3e6557b7f42d02a1eeff157d580ca9d1.tar.gz
Merge branch 'list-style-fixes-dev-docs' into 'master'
Edits to Lists section of Documentation Style Guide See merge request gitlab-org/gitlab-ce!32782
-rw-r--r--doc/development/documentation/styleguide.md41
1 files changed, 24 insertions, 17 deletions
diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md
index 4a50e90a26c..39b5e191a7b 100644
--- a/doc/development/documentation/styleguide.md
+++ b/doc/development/documentation/styleguide.md
@@ -262,7 +262,7 @@ table_display_block: true
## Punctuation
Check the general punctuation rules for the GitLab documentation on the table below.
-Check specific punctuation rules for [list items](#list-items) below.
+Check specific punctuation rules for [lists](#lists) below.
| Rule | Example |
| ---- | ------- |
@@ -274,37 +274,44 @@ Check specific punctuation rules for [list items](#list-items) below.
| 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._ |
-## List items
+## 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 subitem](#nesting-inside-a-list-item).
-- Only use ordered lists when their items describe a sequence of steps to follow:
- Do:
+### Ordered vs. unordered lists
- These are the steps to do something:
+Only use ordered lists when their items describe a sequence of steps to follow.
- 1. First, do step 1
- 1. Then, do step 2
- 1. Finally, do step 3
+Do:
+
+```md
+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:
+Don't:
- This is a list of different features:
+```md
+This is a list of available features:
- 1. Feature 1
- 1. Feature 2
- 1. Feature 3
+1. Feature 1
+1. Feature 2
+1. Feature 3
+```
-**Markup:**
+### Markup
- Use dashes (`-`) for unordered lists instead of asterisks (`*`).
-- Prefix `1.` to each item in an ordered list.
+- Prefix `1.` to every item in an ordered list.
When rendered, the list items will appear with sequential numbering automatically.
-**Punctuation:**
+### 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.
@@ -343,7 +350,7 @@ Do:
- Let's say this is also a complete sentence.
- Not a complete sentence.
-Don't (third item should have a `.` to match the first and second items):
+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.