Skip to content

G
gitlab-ce
Commit a3705457 authored by Susan Tacker's avatar Susan Tacker
Browse files
Options

Merge branch 'selhorn-okr-guidelines-for-nav' into 'master' 

Updates to nav and SVG guidance

See merge request gitlab-org/gitlab!68699
parents 7a6e0e09 9ca6928f
Show whitespace changes
Inline Side-by-side
Showing with 111 additions and 65 deletions
doc/development/documentation/styleguide/index.md
View file @ a3705457
......@@ -1003,9 +1003,23 @@ document to ensure it links to the most recent version of the file.
## Navigation
When documenting navigation through the user interface, use these terms and styles.
### What to call the menus
When documenting how to navigate through the GitLab UI:
- Always use location, then action.
- `From the **Visibility** list,` (location) `select **Public**.` (action)
- Be brief and specific. For example:
- Avoid: `Select **Save** for the changes to take effect.`
- Use instead: `Select **Save**.`
- When selecting from high-level UI elements, use the word **on**.
- Avoid: `From the left sidebar...` or `In the left sidebar...`
- Use instead: `On the left sidebar...`
- If a step must include a reason, start the step with it.
- Avoid: `Select the link in the merge request to view the changes.`
- Use instead: `To view the changes, select the link in the merge request.`
- If a step is optional, start the step with the word `Optional` followed by a period.
- `1. Optional. Enter a name for the dog.`
### Names for menus
Use these terms when referring to the main GitLab user interface
elements:
......@@ -1017,9 +1031,14 @@ elements:
- **Right sidebar**: This is the navigation sidebar on the right of the user
interface, specific to the open issue, merge request, or epic.
### How to document the menus
### Names for UI elements
UI elements, like button and checkbox names, should be **bold**.
Guidance for each individual UI element is in [the word list](word_list.md).
### How to write navigation task steps
To be consistent, use this format when you write about UI navigation.
To be consistent, use this format when you write navigation steps in a task topic.
1. On the top bar, select **Menu > Projects** and find your project.
1. On the left sidebar, select **Settings > CI/CD**.
......@@ -1034,12 +1053,14 @@ Another example:
An Admin Area example:
```markdown
1. On the top bar, select **Menu >** **{admin}** **Admin**.
1. On the top bar, select **Menu > Admin**.
```
This text renders this output:
To select your avatar:
1. On the top bar, select **Menu >** **{admin}** **Admin**.
```markdown
1. On the top bar, in the top right corner, select your avatar.
```
## Images
......@@ -1288,64 +1309,22 @@ For a complete reference on code blocks, see the [Kramdown guide](https://about.
> [Introduced](https://gitlab.com/gitlab-org/gitlab-docs/-/issues/384) in GitLab 12.7.
You can use icons from the [GitLab SVG library](https://gitlab-org.gitlab.io/gitlab-svgs/)
directly in the documentation.
This way, you can achieve a consistent look when writing about interacting with
GitLab user interface elements.
Usage examples:
- Icon with default size (16px): `**{icon-name}**`
Example: `**{tanuki}**` renders as: **{tanuki}**.
- Icon with custom size: `**{icon-name, size}**`
Available sizes (in pixels): 8, 10, 12, 14, 16, 18, 24, 32, 48, and 72
Example: `**{tanuki, 24}**` renders as: **{tanuki, 24}**.
- Icon with custom size and class: `**{icon-name, size, class-name}**`.
directly in the documentation. For example, `**{tanuki}**` renders as: **{tanuki}**.
You can access any class available to this element in GitLab documentation CSS.
In most cases, you should avoid using the icons in text.
However, you can use an icon when hover text is the only
available way to describe a UI element. For example, **Delete** or **Edit** buttons
often have hover text only.
Example with `float-right`, a
[Bootstrap utility class](https://getbootstrap.com/docs/4.4/utilities/float/):
`**{tanuki, 32, float-right}**` renders as: **{tanuki, 32, float-right}**
### When to use icons
Icons should be used sparingly, and only in ways that aid and do not hinder the
readability of the text.
For example, this Markdown adds little to the accompanying text:
```markdown
1. Go to **{home}** **Project information > Details**.
```
1. Go to **{home}** **Project information > Details**.
However, these tables might help the reader connect the text to the user
interface:
```markdown
| Section | Description |
|:-------------------------|:----------------------------------------------------------------------------------------------------------------------------|
| **{overview}** Overview | View your GitLab Dashboard, and administer projects, users, groups, jobs, runners, and Gitaly servers. |
| **{monitor}** Monitoring | View GitLab system information, and information on background jobs, logs, health checks, requests profiles, and audit events. |
| **{messages}** Messages | Send and manage broadcast messages for your users. |
```
When you do use an icon, start with the hover text and follow it with the SVG reference in parentheses.
| Section | Description |
|:-------------------------|:----------------------------------------------------------------------------------------------------------------------------|
| **{overview}** Overview | View your GitLab Dashboard, and administer projects, users, groups, jobs, runners, and Gitaly servers. |
| **{monitor}** Monitoring | View GitLab system information, and information on background jobs, logs, health checks, requests profiles, and audit events. |
| **{messages}** Messages | Send and manage broadcast messages for your users. |
- Avoid: `Select **{pencil}** **Edit**.` This generates as: Select **{pencil}** **Edit**.
- Use instead: `Select **Edit** (**{pencil}**).` This generates as: Select **Edit** (**{pencil}**).
Use an icon when you find yourself having to describe an interface element. For
example:
Do not use words to describe the icon:
- Do: Select the Admin Area icon ( **{admin}** ).
- Don't: Select the Admin Area icon (the wrench icon).
- Avoid: `Select **Erase job log** (the trash icon).`
- Use instead: `Select **Erase job log** (**{remove}**).` This generates as: Select **Erase job log** (**{remove}**).
## Alert boxes
......
doc/development/documentation/styleguide/word_list.md
View file @ a3705457
......@@ -52,6 +52,10 @@ in the handbook when writing about Alpha features.
Instead of **and/or**, use or or rewrite the sentence to spell out both options.
## area
Use [section](#section) instead. The only exception is [the Admin Area](#admin-admin-area).
## below
Try to avoid extra words when referring to an example or table in a documentation page, but if required, use **following** instead.
......@@ -71,6 +75,19 @@ Do not use. Another option is **denylist**. ([Vale](../testing.md#vale) rule: [`
Use lowercase for **boards**, **issue boards**, and **epic boards**.
## box
Use instead of **field** or **text box**. For example:
- In the **Variable name** box, enter `my text`.
## button
Don't use a descriptor.
- Avoid: Select the **Run pipelines** button.
- Use instead: Select **Run pipelines**.
## checkbox
One word, **checkbox**. Do not use **check box**.
......@@ -86,6 +103,16 @@ Always uppercase. No need to spell out on first use.
Do not use. Instead, use **select** with buttons, links, menu items, and lists.
**Select** applies to more devices, while **click** is more specific to a mouse.
## collapse
Use instead of **close** when you are talking about expanding or collapsing a section in the UI.
## confirmation dialog
Use to describe the dialog box that asks you to confirm your action. For example:
- From the confirmation dialog, select **OK**.
## currently
Do not use when talking about the product or its features. The documentation describes the product as it is today. ([Vale](../testing.md#vale) rule: [`CurrentStatus.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/CurrentStatus.yml))
......@@ -113,6 +140,15 @@ Do not use **Developer permissions**. A user who is assigned the Developer role
See [the Microsoft style guide](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/d/disable-disabled) for guidance.
Use **inactive** or **off** instead. ([Vale](../testing.md#vale) rule: [`InclusionAbleism.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionAbleism.yml))
## dropdown, dropdown list
Do not use. Use **list** instead.
Include the descriptor when writing about lists. Start with the list name,
then follow with the item the user should select. For example:
- From the **Visibility** list, select **Public**.
## earlier
Use when talking about version numbers.
......@@ -128,10 +164,6 @@ Do not use. If the user doesn't find the process to be easy, we lose their trust
Do not use Latin abbreviations. Use **for example**, **such as**, **for instance**, or **like** instead. ([Vale](../testing.md#vale) rule: [`LatinTerms.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/LatinTerms.yml))
## expand
Use instead of **open** when you are talking about expanding or collapsing a section in the UI.
## email
Do not use **e-mail** with a hyphen. When plural, use **emails** or **email messages**.
......@@ -156,6 +188,17 @@ Try to avoid. Be as specific as you can. Do not use **and so on** as a replaceme
- Avoid: You can update objects, like merge requests, issues, etc.
- Use instead: You can update objects, like merge requests and issues.
## expand
Use instead of **open** when you are talking about expanding or collapsing a section in the UI.
## field
Use **box** instead of **field** or **text box**.
- Avoid: In the **Variable name** field, enter `my text`.
- Use instead: In the **Variable name** box, enter `my text`.
## foo
Do not use in product documentation. You can use it in our API and contributor documentation, but try to use a clearer and more meaningful example instead.
......@@ -262,6 +305,14 @@ Use when talking about version numbers.
- Avoid: In GitLab 14.1 and higher.
- Use instead: In GitLab 14.1 and later.
## list
Use instead of **dropdown**, **drop-down** or **dropdown list**. You select an item from a list. For example:
- From the **Availability** list, select **public**.
The list name, and the items you select, should be bold.
## log in, log on
Do not use. Use [sign in](#sign-in) instead. If the user interface has **Log in**, you can use it.
......@@ -407,6 +458,22 @@ Do not use. Use **check for completeness** instead. ([Vale](../testing.md#vale)
Do not use when talking about increasing GitLab performance for additional users. The words scale or scaling are sometimes acceptable, but references to increasing GitLab performance for additional users should direct readers to the GitLab [reference architectures](../../../administration/reference_architectures/index.md) page.
## section
Use to describe an area on a page. For example, if a page has lines that separate the UI
into separate areas, refer to these areas as sections.
We often think of expandable/collapsible areas as **sections**. When you refer to expanding
or collapsing a section, don't include the word **section**.
- Avoid: Expand the **Auto DevOps** section.
- Use instead: Expand **Auto DevOps**.
## select
Use with buttons, links, menu items, and lists. **Select** applies to more devices,
while **click** is more specific to a mouse.
## setup, set up
Use **setup** as a noun, and **set up** as a verb. For example:
......
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
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7