summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAchilleas Pipinellis <axil@gitlab.com>2018-05-09 14:45:55 +0000
committerAchilleas Pipinellis <axil@gitlab.com>2018-05-09 14:45:55 +0000
commit1802954b4785fa3d6bd3686f5b6de3094a2eb851 (patch)
treeff7ecb963236570ffa024b207999354fa6450e71
parent063b6b75be97440a96cda109bcb9d448920c7e49 (diff)
parent185f0a3982e52701b421b9c455e2e582a24296f8 (diff)
downloadgitlab-ce-1802954b4785fa3d6bd3686f5b6de3094a2eb851.tar.gz
Merge branch 'docs-update-docstyleguide' into 'master'
Docs: update docs style guidelines Closes #46157 and #45321 See merge request gitlab-org/gitlab-ce!18819
-rw-r--r--doc/development/doc_styleguide.md114
1 files changed, 91 insertions, 23 deletions
diff --git a/doc/development/doc_styleguide.md b/doc/development/doc_styleguide.md
index 540e39aabbd..5d595c33915 100644
--- a/doc/development/doc_styleguide.md
+++ b/doc/development/doc_styleguide.md
@@ -25,23 +25,39 @@ Check the GitLab handbook for the [writing styles guidelines](https://about.gitl
- Use [single spaces][] instead of double spaces
- Jump a line between different markups (e.g., after every paragraph, header, list, etc)
- Capitalize "G" and "L" in GitLab
-- Capitalize feature, products, and methods names. E.g.: GitLab Runner, Geo,
-Issue Boards, Git, Prometheus, Continuous Integration.
+- Use sentence case for titles, headings, labels, menu items, and buttons.
+- Use title case when referring to [features](https://about.gitlab.com/features/) or [products](https://about.gitlab.com/pricing/), and methods. Note that some features are also objects (e.g. "Merge Requests" and "merge requests"). E.g.: GitLab Runner, Geo, Issue Boards, Git, Prometheus, Continuous Integration.
## Formatting
+- Use double asterisks (`**`) to mark a word or text in bold (`**bold**`)
+- Use undescore (`_`) for text in italics (`_italic_`)
+- Jump a line between different markups, for example:
+
+ ```md
+ ## Header
+
+ Paragraph.
+
+ - List item
+ - List item
+ ```
+
+### Punctuation
+
+For punctuation rules, please refer to the [GitLab UX guide](https://design.gitlab.com/content/punctuation/).
+
+### Ordered and unordered lists
+
- Use dashes (`-`) for unordered lists instead of asterisks (`*`)
- Use the number one (`1`) for ordered lists
-- Use underscores (`_`) to mark a word or text in italics
-- Use double asterisks (`**`) to mark a word or text in bold
-- When using lists, prefer not to end each item with a period. You can use
- them if there are multiple sentences, just keep the last sentence without
- a period
+- For punctuation in bullet lists, please refer to the [GitLab UX guide](https://design.gitlab.com/content/punctuation/)
## Headings
-- Add only one H1 title in each document, by adding `#` at the beginning of
- it (when using markdown). For subheadings, use `##`, `###` and so on
+- Add **only one H1** in each document, by adding `#` at the beginning of
+ it (when using markdown). The `h1` will be the document `<title>`.
+- For subheadings, use `##`, `###` and so on
- Avoid putting numbers in headings. Numbers shift, hence documentation anchor
links shift too, which eventually leads to dead links. If you think it is
compelling to add numbers in headings, make sure to at least discuss it with
@@ -110,21 +126,75 @@ Inside the document:
- If a heading is placed right after an image, always add three dashes (`---`)
between the image and the heading
-## Notes
+## Alert boxes
-- Notes should be quoted with the word `Note:` being bold. Use this form:
+Whenever you want to call the attention to a particular sentence,
+use the following markup for highlighting.
- ```md
- >**Note:**
- This is something to note.
- ```
+_Note that the alert boxes only work for one paragraph only. Multiple paragraphs,
+lists, headers, etc will not render correctly._
+
+### Note
+
+```md
+NOTE: **Note:**
+This is something to note.
+```
+
+How it renders in docs.gitlab.com:
+
+NOTE: **Note:**
+This is something to note.
+
+### Tip
+
+```md
+TIP: **Tip:**
+This is a tip.
+```
- which renders to:
+How it renders in docs.gitlab.com:
- >**Note:**
- This is something to note.
+TIP: **Tip:**
+This is a tip.
- If the note spans across multiple lines it's OK to split the line.
+### Caution
+
+```md
+CAUTION: **Caution:**
+This is something to be cautious about.
+```
+
+How it renders in docs.gitlab.com:
+
+CAUTION: **Caution:**
+This is something to be cautious about.
+
+### Danger
+
+```md
+DANGER: **Danger:**
+This is a breaking change, a bug, or something very important to note.
+```
+
+How it renders in docs.gitlab.com:
+
+DANGER: **Danger:**
+This is a breaking change, a bug, or something very important to note.
+
+## Blockquotes
+
+For highlighting a text within a blue blockquote, use this format:
+
+```md
+> This is a blockquote.
+```
+
+which renders in docs.gitlab.com to:
+
+> This is a blockquote.
+
+If the text spans across multiple lines it's OK to split the line.
## Specific sections and terms
@@ -141,7 +211,7 @@ below.
> Introduced in GitLab 8.3.
```
-- If possible every feature should have a link to the MR, issue, or epic that introduced it.
+- Whenever possible, every feature should have a link to the MR, issue, or epic that introduced it.
The above note would be then transformed to:
```md
@@ -156,11 +226,9 @@ below.
the feature is available in:
```md
- > [Introduced][ee-1234] in [GitLab Starter](https://about.gitlab.com/products/) 8.3.
+ > [Introduced][ee-1234] in [GitLab Starter](https://about.gitlab.com/pricing/) 8.3.
```
- Otherwise, leave this mention out.
-
### Product badges
When a feature is available in EE-only tiers, add the corresponding tier according to the