diff options
Diffstat (limited to 'doc/development/documentation/styleguide.md')
| -rw-r--r-- | doc/development/documentation/styleguide.md | 80 |
1 files changed, 43 insertions, 37 deletions
diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md index e610c7595a8..8083f219d4a 100644 --- a/doc/development/documentation/styleguide.md +++ b/doc/development/documentation/styleguide.md @@ -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: `` - 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 |