Commit 15c87796 authored by Mike Lewis's avatar Mike Lewis

Merge branch 'use-colon-in-lists' into 'master'

Add guidance on using colons in bullet lists, and make styleguide adhere closer to styleguide.

Closes #51086

See merge request gitlab-org/gitlab-ce!21549
parents 5031efa0 07554a1d
...@@ -13,10 +13,10 @@ Check the GitLab handbook for the [writing styles guidelines](https://about.gitl ...@@ -13,10 +13,10 @@ Check the GitLab handbook for the [writing styles guidelines](https://about.gitl
## Files ## Files
- [Directory structure](index.md#location-and-naming-documents): place the docs - [Directory structure](index.md#location-and-naming-documents): place the docs
in the correct location in the correct location.
- [Documentation files](index.md#documentation-files): name the files accordingly - [Documentation files](index.md#documentation-files): name the files accordingly.
- [Markdown](../../user/markdown.md): use the GitLab Flavored Markdown in the - [Markdown](../../user/markdown.md): use the GitLab Flavored Markdown in the
documentation documentation.
NOTE: **Note:** NOTE: **Note:**
**Do not** use capital letters, spaces, or special chars in file names, **Do not** use capital letters, spaces, or special chars in file names,
...@@ -30,17 +30,17 @@ a test that will fail if it spots a new `README.md` file. ...@@ -30,17 +30,17 @@ a test that will fail if it spots a new `README.md` file.
- Split up long lines (wrap text), this makes it much easier to review and edit. Only - Split up long lines (wrap text), this makes it much easier to review and edit. Only
double line breaks are shown as a full line break in [GitLab markdown][gfm]. double line breaks are shown as a full line break in [GitLab markdown][gfm].
80-100 characters is a good line length 80-100 characters is a good line length.
- Make sure that the documentation is added in the correct - Make sure that the documentation is added in the correct
[directory](index.md#documentation-directory-structure) and that [directory](index.md#documentation-directory-structure) and that
there's a link to it somewhere useful there's a link to it somewhere useful.
- Do not duplicate information - Do not duplicate information.
- Be brief and clear - Be brief and clear.
- Unless there's a logical reason not to, add documents in alphabetical order - Unless there's a logical reason not to, add documents in alphabetical order.
- Write in US English - Write in US English.
- Use [single spaces][] instead of double spaces - Use [single spaces][] instead of double spaces.
- Jump a line between different markups (e.g., after every paragraph, header, list, etc) - Jump a line between different markups (e.g., after every paragraph, header, list, etc)
- Capitalize "G" and "L" in GitLab - Capitalize "G" and "L" in GitLab.
- Use sentence case for titles, headings, labels, menu items, and buttons. - Use sentence case for titles, headings, labels, menu items, and buttons.
- Use title case when referring to [features](https://about.gitlab.com/features/) or - Use title case when referring to [features](https://about.gitlab.com/features/) or
[products](https://about.gitlab.com/pricing/) (e.g., GitLab Runner, Geo, [products](https://about.gitlab.com/pricing/) (e.g., GitLab Runner, Geo,
...@@ -50,10 +50,9 @@ some features are also objects (e.g. "Merge Requests" and "merge requests"). ...@@ -50,10 +50,9 @@ some features are also objects (e.g. "Merge Requests" and "merge requests").
## Formatting ## Formatting
- Use double asterisks (`**`) to mark a word or text in bold (`**bold**`) - Use double asterisks (`**`) to mark a word or text in bold (`**bold**`).
- Use undescore (`_`) for text in italics (`_italic_`) - Use undescore (`_`) for text in italics (`_italic_`).
- Jump a line between different markups, for example: - Put an empty line between different markups. For example:
```md ```md
## Header ## Header
...@@ -69,9 +68,16 @@ For punctuation rules, please refer to the [GitLab UX guide](https://design.gitl ...@@ -69,9 +68,16 @@ For punctuation rules, please refer to the [GitLab UX guide](https://design.gitl
### Ordered and unordered lists ### Ordered and unordered lists
- Use dashes (`-`) for unordered lists instead of asterisks (`*`) - Use dashes (`-`) for unordered lists instead of asterisks (`*`).
- Use the number one (`1`) for ordered lists - Use the number one (`1`) for ordered lists.
- For punctuation in bullet lists, please refer to the [GitLab UX guide](https://design.gitlab.com/content/punctuation/) - Separate list items from explanatory text with a colon (`:`). For example:
```md
The list is as follows:
- First item: This explains the first item.
- Second item: This explains the second item.
```
- For further guidance on punctuation in bullet lists, please refer to the [GitLab UX guide](https://design.gitlab.com/content/punctuation/).
## Headings ## Headings
...@@ -82,7 +88,7 @@ For punctuation rules, please refer to the [GitLab UX guide](https://design.gitl ...@@ -82,7 +88,7 @@ For punctuation rules, please refer to the [GitLab UX guide](https://design.gitl
- Avoid putting numbers in headings. Numbers shift, hence documentation anchor - Avoid putting numbers in headings. Numbers shift, hence documentation anchor
links shift too, which eventually leads to dead links. If you think it is 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 compelling to add numbers in headings, make sure to at least discuss it with
someone in the Merge Request someone in the Merge Request.
- [Avoid using symbols and special chars](https://gitlab.com/gitlab-com/gitlab-docs/issues/84) - [Avoid using symbols and special chars](https://gitlab.com/gitlab-com/gitlab-docs/issues/84)
in headers. Whenever possible, they should be plain and short text. in headers. Whenever possible, they should be plain and short text.
- Avoid adding things that show ephemeral statuses. For example, if a feature is - Avoid adding things that show ephemeral statuses. For example, if a feature is
...@@ -92,8 +98,8 @@ For punctuation rules, please refer to the [GitLab UX guide](https://design.gitl ...@@ -92,8 +98,8 @@ For punctuation rules, please refer to the [GitLab UX guide](https://design.gitl
of the following GitLab members for a review: `@axil` or `@marcia`. of the following GitLab members for a review: `@axil` or `@marcia`.
This is to ensure that no document with wrong heading is going This is to ensure that no document with wrong heading is going
live without an audit, thus preventing dead links and redirection issues when live without an audit, thus preventing dead links and redirection issues when
corrected corrected.
- Leave exactly one new line after a heading - Leave exactly one new line after a heading.
## Links ## Links
...@@ -120,11 +126,11 @@ For punctuation rules, please refer to the [GitLab UX guide](https://design.gitl ...@@ -120,11 +126,11 @@ For punctuation rules, please refer to the [GitLab UX guide](https://design.gitl
To indicate the steps of navigation through the UI: To indicate the steps of navigation through the UI:
- Use the exact word as shown in the UI, including any capital letters as-is - Use the exact word as shown in the UI, including any capital letters as-is.
- Use bold text for navigation items and the char `>` as separator - Use bold text for navigation items and the char `>` as separator
(e.g., `Navigate to your project's **Settings > CI/CD**` ) (e.g., `Navigate to your project's **Settings > CI/CD**` ).
- If there are any expandable menus, make sure to mention that the user - If there are any expandable menus, make sure to mention that the user
needs to expand the tab to find the settings you're referring to needs to expand the tab to find the settings you're referring to.
## Images ## Images
...@@ -149,12 +155,12 @@ Inside the document: ...@@ -149,12 +155,12 @@ Inside the document:
`![Proper description what the image is about](img/document_image_title.png)` `![Proper description what the image is about](img/document_image_title.png)`
- Always use a proper description for what the image is about. That way, when a - Always use a proper description for what the image is about. That way, when a
browser fails to show the image, this text will be used as an alternative browser fails to show the image, this text will be used as an alternative
description description.
- If there are consecutive images with little text between them, always add - If there are consecutive images with little text between them, always add
three dashes (`---`) between the image and the text to create a horizontal three dashes (`---`) between the image and the text to create a horizontal
line for better clarity line for better clarity.
- If a heading is placed right after an image, always add three dashes (`---`) - If a heading is placed right after an image, always add three dashes (`---`)
between the image and the heading between the image and the heading.
## Alert boxes ## Alert boxes
...@@ -262,18 +268,18 @@ below. ...@@ -262,18 +268,18 @@ below.
When a feature is available in EE-only tiers, add the corresponding tier according to the When a feature is available in EE-only tiers, add the corresponding tier according to the
feature availability: feature availability:
- For GitLab Starter and GitLab.com Bronze: `**[STARTER]**` - For GitLab Starter and GitLab.com Bronze: `**[STARTER]**`.
- For GitLab Premium and GitLab.com Silver: `**[PREMIUM]**` - For GitLab Premium and GitLab.com Silver: `**[PREMIUM]**`.
- For GitLab Ultimate and GitLab.com Gold: `**[ULTIMATE]**` - For GitLab Ultimate and GitLab.com Gold: `**[ULTIMATE]**`.
- For GitLab Core and GitLab.com Free: `**[CORE]**` - For GitLab Core and GitLab.com Free: `**[CORE]**`.
To exclude GitLab.com tiers (when the feature is not available in GitLab.com), add the To exclude GitLab.com tiers (when the feature is not available in GitLab.com), add the
keyword "only": keyword "only":
- For GitLab Starter: `**[STARTER ONLY]**` - For GitLab Starter: `**[STARTER ONLY]**`.
- For GitLab Premium: `**[PREMIUM ONLY]**` - For GitLab Premium: `**[PREMIUM ONLY]**`.
- For GitLab Ultimate: `**[ULTIMATE ONLY]**` - For GitLab Ultimate: `**[ULTIMATE ONLY]**`.
- For GitLab Core: `**[CORE ONLY]**` - For GitLab Core: `**[CORE ONLY]**`.
The tier should be ideally added to headers, so that the full badge will be displayed. The tier should be ideally added to headers, so that the full badge will be displayed.
But it can be also mentioned from paragraphs, list items, and table cells. For these cases, But it can be also mentioned from paragraphs, list items, and table cells. For these cases,
...@@ -328,8 +334,8 @@ prefer to document it in the CE docs to avoid duplication. ...@@ -328,8 +334,8 @@ prefer to document it in the CE docs to avoid duplication.
Configuration settings include: Configuration settings include:
- settings that touch configuration files in `config/` - Settings that touch configuration files in `config/`.
- NGINX settings and settings in `lib/support/` in general - NGINX settings and settings in `lib/support/` in general.
When there is a list of steps to perform, usually that entails editing the When there is a list of steps to perform, usually that entails editing the
configuration file and reconfiguring/restarting GitLab. In such case, follow configuration file and reconfiguring/restarting GitLab. In such case, follow
......
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