diff options
Diffstat (limited to 'doc/development/documentation/styleguide/index.md')
| -rw-r--r-- | doc/development/documentation/styleguide/index.md | 67 |
1 files changed, 51 insertions, 16 deletions
diff --git a/doc/development/documentation/styleguide/index.md b/doc/development/documentation/styleguide/index.md index 72491ab3a33..1382ec263f2 100644 --- a/doc/development/documentation/styleguide/index.md +++ b/doc/development/documentation/styleguide/index.md @@ -317,8 +317,8 @@ create an issue or an MR to propose a change to the user interface text. #### Feature names -- *Feature names are typically lowercase*. -- *Some features are capitalized*, typically nouns naming GitLab-specific +- Feature names are typically lowercase. +- Some features are capitalized, typically nouns that name GitLab-specific capabilities or tools. See the [word list](word_list.md) for details. @@ -404,13 +404,13 @@ Some contractions, however, should be avoided: | Do | Don't | |------------------------------------------|-----------------------------------------| - | Do *not* install X with Y. | *Don't* install X with Y. | + | Do not install X with Y. | Don't install X with Y. | - Do not use contractions in reference documentation. For example: | Do | Don't | |------------------------------------------|-----------------------------------------| - | Do *not* set a limit greater than 1000. | *Don't* set a limit greater than 1000. | + | Do not set a limit greater than 1000. | Don't set a limit greater than 1000. | | For `parameter1`, the default is 10. | For `parameter1`, the default's 10. | - Avoid contractions in error messages. Examples: @@ -701,7 +701,7 @@ that's best described by a matrix, tables are the best choice. To keep tables accessible and scannable, tables should not have any empty cells. If there is no otherwise meaningful value for a cell, consider entering -*N/A* (for 'not applicable') or *none*. +**N/A** for 'not applicable' or **None**. To help tables be easier to maintain, consider adding additional spaces to the column widths to make them consistent. For example: @@ -1026,18 +1026,13 @@ document to ensure it links to the most recent version of the file. When documenting how to navigate through the GitLab UI: - Always use location, then action. - - `From the **Visibility** list,` (location) `select **Public**.` (action) + - From the **Visibility** dropdown 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.` + - Do: Select **Save**. + - Do not: Select **Save** for the changes to take effect. +- If a step must include a reason, start the step with it. This helps the user scan more quickly. + - Do: To view the changes, in the merge request, select the link. + - Do not: Select the link in the merge request to view the changes. ### Names for menus @@ -1060,15 +1055,19 @@ Guidance for each individual UI element is in [the word list](word_list.md). To be consistent, use this format when you write navigation steps in a task topic. +```markdown 1. On the top bar, select **Menu > Projects** and find your project. 1. On the left sidebar, select **Settings > CI/CD**. 1. Expand **General pipelines**. +``` Another example: +```markdown 1. On the top bar, select **Menu > Groups** and find your group. 1. On the left sidebar, select **Settings > CI/CD**. 1. Expand **General pipelines**. +``` An Admin Area example: @@ -1082,6 +1081,42 @@ To select your avatar: 1. On the top bar, in the top right corner, select your avatar. ``` +### Optional steps + +If a step is optional, start the step with the word `Optional` followed by a period. + +For example: + +```markdown +1. Optional. Enter a description for the job. +``` + +### Documenting multiple fields at once + +If the UI text sufficiently explains the fields in a section, do not include a task step for every field. +Instead, summarize multiple fields in a single task step. + +Use the phrase **Complete the fields**. + +For example: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Repository**. +1. Expand **Push rules**. +1. Complete the fields. + +If you are documenting multiple fields and only one field needs explanation, do it in the same step: + +1. Expand **Push rules**. +1. Complete the fields. **Branch name** must be a regular expression. + +To describe multiple fields, use bullets: + +1. Expand **General pipelines**. +1. Complete the fields. + - **Branch name** must be a regular expression. + - **User** must be a user with at least the **Maintainer** role. + ## Images Images, including screenshots, can help a reader better understand a concept. |