diff options
author | Evan Read <eread@gitlab.com> | 2018-10-10 16:07:03 +1000 |
---|---|---|
committer | Evan Read <eread@gitlab.com> | 2019-01-07 14:06:55 +1000 |
commit | 40aba81218e4c1e42913ffa9e7cdf14478c734d9 (patch) | |
tree | 6cde8527809f5909dcb06acaff8539115ba0e089 | |
parent | b83be5032716548ea9d738a03e0a20f660dc04ac (diff) | |
download | gitlab-ce-40aba81218e4c1e42913ffa9e7cdf14478c734d9.tar.gz |
Add new styleguide sections for verbs
Also fixes spelling, and makes the Markdown style more consistent.
-rw-r--r-- | doc/development/documentation/styleguide.md | 34 |
1 files changed, 31 insertions, 3 deletions
diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md index 829dcf18926..07e247da5e6 100644 --- a/doc/development/documentation/styleguide.md +++ b/doc/development/documentation/styleguide.md @@ -210,7 +210,7 @@ For other punctuation rules, please refer to the - Use inline link markdown markup `[Text](https://example.com)`. It's easier to read, review, and maintain. **Do not** use `[Text][identifier]`. - To link to internal documentation, use relative links, not full URLs. Use `../` to - navigate tp high-level directories, and always add the file name `file.md` at the + navigate to high-level directories, and always add the file name `file.md` at the end of the link with the `.md` extension, not `.html`. Example: instead of `[text](../../merge_requests/)`, use `[text](../../merge_requests/index.md)` or, `[text](../../ci/README.md)`, or, @@ -386,8 +386,32 @@ Which renders to: ## Specific sections and terms -To mention and/or reference specific terms in GitLab, please follow the styles -below. +To maintain consistency through GitLab documentation, the following guides documentation authors +on agreed styles and usage of terms. + +### Describing UI elements + +The following are styles to follow when describing UI elements on a screen: + +- For elements with a visible label, use that label in bold with matching case. For example, `the **Cancel** button`. +- For elements with a tooltip or hover label, use that label in bold with matching case. For example, `the **Add status emoji** button`. + +### Verbs for UI elements + +The following are verbs that should be used in preference to alternatives. + +| Use | Used for | Do not use | +|:---------|:--------------------------------|:---------------------------| +| "click" | buttons, links, menu items | "hit", "press", "select" | +| "check" | checkboxes | "enable", "click", "press" | +| "select" | dropdowns | "pick" | +| "expand" | expandable sections | "open" | + +### Other Verbs + +| Use | Used for | Do not use | +|:---------|:--------------------------------|:---------------------------| +| "go" | making a browser go to location | "navigate", "open" | ### GitLab versions and tiers @@ -460,6 +484,10 @@ the special markup `**[STARTER]**` will generate a `span` element to trigger the badges and tooltips (`<span class="badge-trigger starter">`). When the keyword "only" is added, the corresponding GitLab.com badge will not be displayed. +## Specific sections + +Certain styles should be applied to specific sections. Styles for specific sections are outlined below. + ### GitLab Restart There are many cases that a restart/reconfigure of GitLab is required. To |