Merge branch 'ux-copy-capitalization-punctuation' into 'master'
Improve UX copy docs on capitalization and punctuation See merge request !8439
This commit is contained in:
commit
6ca4b6a38d
|
@ -4,12 +4,14 @@ The copy for GitLab is clear and direct. We strike a clear balance between profe
|
||||||
|
|
||||||
The copy and messaging is a core part of the experience of GitLab and the conversation with our users. Follow the below conventions throughout GitLab.
|
The copy and messaging is a core part of the experience of GitLab and the conversation with our users. Follow the below conventions throughout GitLab.
|
||||||
|
|
||||||
|
Portions of this page are inspired by work found in the [Material Design guidelines][material design].
|
||||||
|
|
||||||
>**Note:**
|
>**Note:**
|
||||||
We are currently inconsistent with this guidance. Images below are created to illustrate the point. As this guidance is refined, we will ensure that our experiences align.
|
We are currently inconsistent with this guidance. Images below are created to illustrate the point. As this guidance is refined, we will ensure that our experiences align.
|
||||||
|
|
||||||
## Contents
|
## Contents
|
||||||
* [Brevity](#brevity)
|
* [Brevity](#brevity)
|
||||||
* [Sentence case](#sentence-case)
|
* [Capitalization and punctuation](#capitalization-and-punctuation)
|
||||||
* [Terminology](#terminology)
|
* [Terminology](#terminology)
|
||||||
|
|
||||||
---
|
---
|
||||||
|
@ -29,8 +31,71 @@ Preferrably use context and placement of controls to make it obvious what clicki
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Sentence case
|
## Capitalization and punctuation
|
||||||
Use sentence case for all titles, headings, labels, menu items, and buttons.
|
|
||||||
|
### Case
|
||||||
|
Use sentence case for titles, headings, labels, menu items, and buttons. Use title case when referring to [features][features] or [products][products]. Note that some features are also objects (e.g. “Merge Requests” and “merge requests”).
|
||||||
|
|
||||||
|
| :white_check_mark: Do | :no_entry_sign: Don’t |
|
||||||
|
| --- | --- |
|
||||||
|
| Add issues to the Issue Board feature in GitLab Hosted | Add Issues To The Issue Board Feature In GitLab Hosted |
|
||||||
|
|
||||||
|
### Avoid periods
|
||||||
|
Avoid using periods in solitary sentences in these elements:
|
||||||
|
|
||||||
|
* Labels
|
||||||
|
* Hover text
|
||||||
|
* Bulleted lists
|
||||||
|
* Dialog body text
|
||||||
|
|
||||||
|
Periods should be used for:
|
||||||
|
|
||||||
|
* Lists or dialogs with multiple sentences
|
||||||
|
* Any sentence followed by a link
|
||||||
|
|
||||||
|
| :white_check_mark: **Do** place periods after sentences followed by a link | :no_entry_sign: **Don’t** place periods after a link if it‘s not followed by a sentence |
|
||||||
|
| --- | --- |
|
||||||
|
| Mention someone to notify them. [Learn more](#) | Mention someone to notify them. [Learn more](#). |
|
||||||
|
|
||||||
|
| :white_check_mark: **Do** skip periods after solo sentences of body text | :no_entry_sign: **Don’t** place periods after body text if there is only a single sentence |
|
||||||
|
| --- | --- |
|
||||||
|
| To see the available commands, enter `/gitlab help` | To see the available commands, enter `/gitlab help`. |
|
||||||
|
|
||||||
|
### Use contractions
|
||||||
|
Don’t make a sentence harder to understand just to follow this rule. For example, “do not” can give more emphasis than “don’t” when needed.
|
||||||
|
|
||||||
|
| :white_check_mark: Do | :no_entry_sign: Don’t |
|
||||||
|
| --- | --- |
|
||||||
|
| it’s, can’t, wouldn’t, you’re, you’ve, haven’t, don’t | it is, cannot, would not, it’ll, should’ve |
|
||||||
|
|
||||||
|
### Use numerals for numbers
|
||||||
|
Use “1, 2, 3” instead of “one, two, three” for numbers. One exception is when mixing uses of numbers, such as “Enter two 3s.”
|
||||||
|
|
||||||
|
| :white_check_mark: Do | :no_entry_sign: Don’t |
|
||||||
|
| --- | --- |
|
||||||
|
| 3 new commits | Three new commits |
|
||||||
|
|
||||||
|
### Punctuation
|
||||||
|
Omit punctuation after phrases and labels to create a cleaner and more readable interface. Use punctuation to add clarity or be grammatically correct.
|
||||||
|
|
||||||
|
| Punctuation mark | Copy and paste | HTML entity | Unicode | Mac shortcut | Windows shortcut | Description |
|
||||||
|
|---|---|---|---|---|---|---|
|
||||||
|
| Period | **.** | | | | | Omit for single sentences in affordances like labels, hover text, bulleted lists, and dialog body text.<br><br>Use in lists or dialogs with multiple sentences, and any sentence followed by a link or inline code.<br><br>Place inside quotation marks unless you’re telling the reader what to enter and it’s ambiguous whether to include the period. |
|
||||||
|
| Comma | **,** | | | | | Place inside quotation marks.<br><br>Use a [serial comma][serial comma] in lists of three or more terms. |
|
||||||
|
| Exclamation point | **!** | | | | | Avoid exclamation points as they tend to come across as shouting. Some exceptions include greetings or congratulatory messages. |
|
||||||
|
| Colon | **:** | `:` | `\u003A` | | | Omit from labels, for example, in the labels for fields in a form. |
|
||||||
|
| Apostrophe | **’** | `’` | `\u2019` | <kbd>⌥ Option</kbd>+<kbd>⇧ Shift</kbd>+<kbd>]</kbd> | <kbd>Alt</kbd>+<kbd>0 1 4 6</kbd> | Use for contractions (I’m, you’re, ’89) and to show possession.<br><br>To show possession, add an *’s* to all single nouns and names, even if they already end in an *s*: “Your issues’s status was changed.” For singular proper names ending in *s*, use only an apostrophe: “James’ commits.” For plurals of a single letter, add an *’s*: “Dot your i’s and cross your t’s.”<br><br>Omit for decades or acronyms: “the 1990s”, “MRs.” |
|
||||||
|
| Quotation marks | **“**<br><br>**”**<br><br>**‘**<br><br>**’** | `“`<br><br>`”`<br><br>`‘`<br><br>`’` | `\u201C`<br><br>`\u201D`<br><br>`\u2018`<br><br>`\u2019` | <kbd>⌥ Option</kbd>+<kbd>[</kbd><br><br><kbd>⌥ Option</kbd>+<kbd>⇧ Shift</kbd>+<kbd>[</kbd><br><br><kbd>⌥ Option</kbd>+<kbd>]</kbd><br><br><kbd>⌥ Option</kbd>+<kbd>⇧ Shift</kbd>+<kbd>]</kbd> | <kbd>Alt</kbd>+<kbd>0 1 4 7</kbd><br><br><kbd>Alt</kbd>+<kbd>0 1 4 8</kbd><br><br><kbd>Alt</kbd>+<kbd>0 1 4 5</kbd><br><br><kbd>Alt</kbd>+<kbd>0 1 4 6</kbd> | Use proper quotation marks (also known as smart quotes, curly quotes, or typographer’s quotes) for quotes. Single quotation marks are used for quotes inside of quotes.<br><br>The right single quotation mark symbol is also used for apostrophes.<br><br>Don’t use primes, straight quotes, or free-standing accents for quotation marks. |
|
||||||
|
| Primes | **′**<br><br>**″** | `′`<br><br>`″` | `\u2032`<br><br>`\u2033` | | <kbd>Alt</kbd>+<kbd>8 2 4 2</kbd><br><br><kbd>Alt</kbd>+<kbd>8 2 4 3</kbd> | Use prime (′) only in abbreviations for feet, arcminutes, and minutes: 3° 15′<br><br>Use double-prime (″) only in abbreviations for inches, arcseconds, and seconds: 3° 15′ 35″<br><br>Don’t use quotation marks, straight quotes, or free-standing accents for primes. |
|
||||||
|
| Straight quotes and accents | **"**<br><br>**'**<br><br>**`**<br><br>**´** | `"`<br><br>`'`<br><br>```<br><br>`´` | `\u0022`<br><br>`\u0027`<br><br>`\u0060`<br><br>`\u00B4` | | | Don’t use straight quotes or free-standing accents for primes or quotation marks.<br><br>Proper typography never uses straight quotes. They are left over from the age of typewriters and their only modern use is for code. |
|
||||||
|
| Ellipsis | **…** | `…` | | <kbd>⌥ Option</kbd>+<kbd>;</kbd> | <kbd>Alt</kbd>+<kbd>0 1 3 3</kbd> | Use to indicate an action in progress (“Downloading…”) or incomplete or truncated text. No space before the ellipsis.<br><br>Omit from menu items or buttons that open a dialog or start some other process. |
|
||||||
|
| Chevrons | **«**<br><br>**»**<br><br>**‹**<br><br>**›**<br><br>**<**<br><br>**>** | `«`<br><br>`»`<br><br>`‹`<br><br>`›`<br><br>`<`<br><br>`>` | `\u00AB`<br><br>`\u00BB`<br><br>`\u2039`<br><br>`\u203A`<br><br>`\u003C`<br><br>`\u003E`<br><br> | | | Omit from links or buttons that open another page or move to the next or previous step in a process. Also known as angle brackets, angular quote brackets, or guillemets. |
|
||||||
|
| Em dash | **—** | `—` | `\u2014` | <kbd>⌥ Option</kbd>+<kbd>⇧ Shift</kbd>+<kbd>-</kbd> | <kbd>Alt</kbd>+<kbd>0 1 5 1</kbd> | Avoid using dashes to separate text. If you must use dashes for this purpose — like this — use an em dash surrounded by spaces. |
|
||||||
|
| En dash | **–** | `–` | `\u2013` | <kbd>⌥ Option</kbd>+<kbd>-</kbd> | <kbd>Alt</kbd>+<kbd>0 1 5 0</kbd> | Use an en dash without spaces instead of a hyphen to indicate a range of values, such as numbers, times, and dates: “3–5 kg”, “8:00 AM–12:30 PM”, “10–17 Jan” |
|
||||||
|
| Hyphen | **-** | | | | | Use to represent negative numbers, or to avoid ambiguity in adjective-noun or noun-participle pairs. Example: “anti-inflammatory”; “5-mile walk.”<br><br>Omit in commonly understood terms and adverbs that end in *ly*: “frontend”, “greatly improved performance.”<br><br>Omit in the term “open source.” |
|
||||||
|
| Parentheses | **( )** | | | | | Use only to define acronyms or jargon: “Secure web connections are based on a technology called SSL (the secure sockets layer).”<br><br>Avoid other uses and instead rewrite the text, or use dashes or commas to set off the information. If parentheses are required: If the parenthetical is a complete, independent sentence, place the period inside the parentheses; if not, the period goes outside. |
|
||||||
|
|
||||||
|
When using the <kbd>Alt</kbd> keystrokes in Windows, use the numeric keypad, not the row of numbers above the alphabet, and be sure Num Lock is turned on.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
@ -48,15 +113,15 @@ Only use the terms in the tables below.
|
||||||
| Deleted |
|
| Deleted |
|
||||||
|
|
||||||
>**Example:**
|
>**Example:**
|
||||||
Use `5 open issues` and don't use `5 pending issues`.
|
Use `5 open issues` and don’t use `5 pending issues`.
|
||||||
|
|
||||||
#### Verbs (actions)
|
#### Verbs (actions)
|
||||||
|
|
||||||
| Term | Use | Don't |
|
| Term | Use | Don’t |
|
||||||
| ---- | --- | --- |
|
| ---- | --- | --- |
|
||||||
| Add | Add an issue | Don't use `create` or `new` |
|
| Add | Add an issue | Don’t use `create` or `new` |
|
||||||
| View | View an open or closed issue ||
|
| View | View an open or closed issue ||
|
||||||
| Edit | Edit an open or closed issue | Don't use `update` |
|
| Edit | Edit an open or closed issue | Don’t use `update` |
|
||||||
| Close | Close an open issue ||
|
| Close | Close an open issue ||
|
||||||
| Re-open | Re-open a closed issue | There should never be a need to use `open` as a verb |
|
| Re-open | Re-open a closed issue | There should never be a need to use `open` as a verb |
|
||||||
| Delete | Delete an open or closed issue ||
|
| Delete | Delete an open or closed issue ||
|
||||||
|
@ -67,7 +132,7 @@ When viewing a list of issues, there is a button that is labeled `Add`. Given th
|
||||||
|
|
||||||
![Add issue button](img/copy-form-addissuebutton.png)
|
![Add issue button](img/copy-form-addissuebutton.png)
|
||||||
|
|
||||||
The form should be titled `Add issue`. The submit button should be labeled `Submit`. Don't use `Add`, `Create`, `New`, or `Save changes`. The cancel button should be labeled `Cancel`. Don't use `Back`.
|
The form should be titled `Add issue`. The submit button should be labeled `Submit`. Don’t use `Add`, `Create`, `New`, or `Save changes`. The cancel button should be labeled `Cancel`. Don’t use `Back`.
|
||||||
|
|
||||||
![Add issue form](img/copy-form-addissueform.png)
|
![Add issue form](img/copy-form-addissueform.png)
|
||||||
|
|
||||||
|
@ -77,7 +142,7 @@ When in context of an issue, the affordance to edit it is labeled `Edit`. If the
|
||||||
|
|
||||||
![Edit issue button](img/copy-form-editissuebutton.png)
|
![Edit issue button](img/copy-form-editissuebutton.png)
|
||||||
|
|
||||||
The form should be titled `Edit issue`. The submit button should be labeled `Save`. Don't use `Edit`, `Update`, `Submit`, or `Save changes`. The cancel button should be labeled `Cancel`. Don't use `Back`.
|
The form should be titled `Edit issue`. The submit button should be labeled `Save`. Don’t use `Edit`, `Update`, `Submit`, or `Save changes`. The cancel button should be labeled `Cancel`. Don’t use `Back`.
|
||||||
|
|
||||||
![Edit issue form](img/copy-form-editissueform.png)
|
![Edit issue form](img/copy-form-editissueform.png)
|
||||||
|
|
||||||
|
@ -93,7 +158,7 @@ The form should be titled `Edit issue`. The submit button should be labeled `Sav
|
||||||
|
|
||||||
#### Verbs (actions)
|
#### Verbs (actions)
|
||||||
|
|
||||||
| Term | Use | Don't |
|
| Term | Use | Don’t |
|
||||||
| ---- | --- | --- |
|
| ---- | --- | --- |
|
||||||
| Add | Add a merge request | Do not use `create` or `new` |
|
| Add | Add a merge request | Do not use `create` or `new` |
|
||||||
| View | View an open or merged merge request ||
|
| View | View an open or merged merge request ||
|
||||||
|
@ -107,5 +172,16 @@ The form should be titled `Edit issue`. The submit button should be labeled `Sav
|
||||||
#### Comment
|
#### Comment
|
||||||
A **comment** is a written piece of text that users of GitLab can create. Comments have the meta data of author and timestamp. Comments can be added in a variety of contexts, such as issues, merge requests, and discussions.
|
A **comment** is a written piece of text that users of GitLab can create. Comments have the meta data of author and timestamp. Comments can be added in a variety of contexts, such as issues, merge requests, and discussions.
|
||||||
|
|
||||||
#### Dicussion
|
#### Discussion
|
||||||
A **discussion** is a group of 1 or more comments. A discussion can include subdiscussions. Some discussions have the special capability of being able to be **resolved**. Both the comments in the discussion and the discussion itself can be resolved.
|
A **discussion** is a group of 1 or more comments. A discussion can include subdiscussions. Some discussions have the special capability of being able to be **resolved**. Both the comments in the discussion and the discussion itself can be resolved.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
Portions of this page are modifications based on work created and shared by the [Android Open Source Project][android project] and used according to terms described in the [Creative Commons 2.5 Attribution License][creative commons].
|
||||||
|
|
||||||
|
[material design]: https://material.io/guidelines/
|
||||||
|
[features]: https://about.gitlab.com/features/ "GitLab features page"
|
||||||
|
[products]: https://about.gitlab.com/products/ "GitLab products page"
|
||||||
|
[serial comma]: https://en.wikipedia.org/wiki/Serial_comma "“Serial comma” in Wikipedia"
|
||||||
|
[android project]: http://source.android.com/
|
||||||
|
[creative commons]: http://creativecommons.org/licenses/by/2.5/
|
Loading…
Reference in New Issue