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
## Files
- [Directory structure](index.md#location-and-naming-documents): place the docs
in the correct location
- [Documentation files](index.md#documentation-files): name the files accordingly
in the correct location.
- [Documentation files](index.md#documentation-files): name the files accordingly.
- [Markdown](../../user/markdown.md): use the GitLab Flavored Markdown in the
documentation
documentation.
NOTE: **Note:**
**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.
- 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].
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
[directory](index.md#documentation-directory-structure) and that
there's a link to it somewhere useful
- Do not duplicate information
- Be brief and clear
- Unless there's a logical reason not to, add documents in alphabetical order
- Write in US English
- Use [single spaces][] instead of double spaces
there's a link to it somewhere useful.
- Do not duplicate information.
- Be brief and clear.
- Unless there's a logical reason not to, add documents in alphabetical order.
- Write in US English.
- 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 "G" and "L" in GitLab.
- 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/) (e.g., GitLab Runner, Geo,
......@@ -50,10 +50,9 @@ some features are also objects (e.g. "Merge Requests" and "merge requests").
## 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:
- Use double asterisks (`**`) to mark a word or text in bold (`**bold**`).
- Use undescore (`_`) for text in italics (`_italic_`).
- Put an empty line between different markups. For example:
```md
## Header
......@@ -69,9 +68,16 @@ For punctuation rules, please refer to the [GitLab UX guide](https://design.gitl
### Ordered and unordered lists
- Use dashes (`-`) for unordered lists instead of asterisks (`*`)
- 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/)
- Use dashes (`-`) for unordered lists instead of asterisks (`*`).
- Use the number one (`1`) for ordered lists.
- 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
......@@ -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
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
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)
in headers. Whenever possible, they should be plain and short text.
- 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
of the following GitLab members for a review: `@axil` or `@marcia`.
This is to ensure that no document with wrong heading is going
live without an audit, thus preventing dead links and redirection issues when
corrected
- Leave exactly one new line after a heading
corrected.
- Leave exactly one new line after a heading.
## Links
......@@ -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:
- 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
(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
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
......@@ -149,12 +155,12 @@ Inside the document:
`![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
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
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 (`---`)
between the image and the heading
between the image and the heading.
## Alert boxes
......@@ -262,18 +268,18 @@ below.
When a feature is available in EE-only tiers, add the corresponding tier according to the
feature availability:
- For GitLab Starter and GitLab.com Bronze: `**[STARTER]**`
- For GitLab Premium and GitLab.com Silver: `**[PREMIUM]**`
- For GitLab Ultimate and GitLab.com Gold: `**[ULTIMATE]**`
- For GitLab Core and GitLab.com Free: `**[CORE]**`
- For GitLab Starter and GitLab.com Bronze: `**[STARTER]**`.
- For GitLab Premium and GitLab.com Silver: `**[PREMIUM]**`.
- For GitLab Ultimate and GitLab.com Gold: `**[ULTIMATE]**`.
- For GitLab Core and GitLab.com Free: `**[CORE]**`.
To exclude GitLab.com tiers (when the feature is not available in GitLab.com), add the
keyword "only":
- For GitLab Starter: `**[STARTER ONLY]**`
- For GitLab Premium: `**[PREMIUM ONLY]**`
- For GitLab Ultimate: `**[ULTIMATE ONLY]**`
- For GitLab Core: `**[CORE ONLY]**`
- For GitLab Starter: `**[STARTER ONLY]**`.
- For GitLab Premium: `**[PREMIUM ONLY]**`.
- For GitLab Ultimate: `**[ULTIMATE ONLY]**`.
- For GitLab Core: `**[CORE ONLY]**`.
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,
......@@ -328,8 +334,8 @@ prefer to document it in the CE docs to avoid duplication.
Configuration settings include:
- settings that touch configuration files in `config/`
- NGINX settings and settings in `lib/support/` in general
- Settings that touch configuration files in `config/`.
- NGINX settings and settings in `lib/support/` in general.
When there is a list of steps to perform, usually that entails editing the
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