From f92ea120bae61c071f8588befd2c82ec5ce0e302 Mon Sep 17 00:00:00 2001 From: Victor Wu Date: Mon, 14 Nov 2016 18:52:09 +0000 Subject: [ci skip] Link to the copy (messaging) page. Add new file for copy (messaging) guidelines Update copy guidelines Fix typo Add forms to guidelines Simplify Copy heading Refine copy page. Add images and table Fix toc link on Copy page --- doc/development/ux_guide/copy.md | 78 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 78 insertions(+) create mode 100644 doc/development/ux_guide/copy.md (limited to 'doc/development/ux_guide/copy.md') diff --git a/doc/development/ux_guide/copy.md b/doc/development/ux_guide/copy.md new file mode 100644 index 00000000000..03392a003ee --- /dev/null +++ b/doc/development/ux_guide/copy.md @@ -0,0 +1,78 @@ +# Copy + +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. + +>**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. + +## Contents +* [Brevity](#brevity) +* [Forms](#forms) +* [Terminology](#terminology) + +--- + +## Brevity +Users will skim content, rather than read text carefully. +When familiar with a web app, users rely on muscle memory, and may read even less when moving quickly. +A good experience should quickly orient a user, regardless of their experience, to the purpose of the current screen. This should happen without the user having to consciously read long strings of text. +In general, text is burdensome and adds cognitive load. This is especially pronounced in a powerful productivity tool such as GitLab. +We should _not_ rely on words as a crutch to explain the purpose of a screen. +The current navigation and composition of the elements on the screen should get the user 95% there, with the remaining 5% being specific elements such as text. +This means that, as a rule, copy should be very short. A long message or label is a red flag hinting at design that needs improvement. + +>**Example:** +Use `Add` instead of `Add issue` as a button label. +Preferrably use context and placement of controls to make it obvious what clicking on them will do. + +--- + +## Forms + +### Adding items + +When viewing a list of issues, there is a button that is labeled `Add`. Given the context in the example, it is clearly referring to issues. If the context were not clear enough, the label could be `Add issue`. Clicking the button will bring you to the `Add issue` form. Other add flows should be similar. + +![Add issue button](img/copy-form-addissuebutton.png) + +The form should be titled `Add issue`. The submit button should be labeled `Save` or `Submit`. Do not use `Add`, `Create`, `New`, or `Save Changes`. The cancel button should be labeled `Cancel`. Do not use `Back`. + +![Add issue form](img/copy-form-addissueform.png) + +### Editing items + +When in context of an issue, the affordance to edit it is labeled `Edit`. If the context is not clear enough, `Edit issue` could be considered. Other edit flows should be similar. + +![Edit issue button](img/copy-form-editissuebutton.png) + +The form should be titled `Edit Issue`. The submit button should be labeled `Save`. Do not use `Edit`, `Update`, `New`, or `Save Changes`. The cancel button should be labeled `Cancel`. Do not use `Back`. + +![Edit issue form](img/copy-form-editissueform.png) + +--- + +## Terminology + +### Issues + +#### Adjectives (states) + +| Term | Use | +| ---- | --- | +| Open | Issue is active | +| Closed | Issue is no longer active | + +>**Example:** +Use `5 open issues` and do not use `5 pending issues`. +Only use the adjectives in the table above. + +#### Verbs (actions) + +| Term | Use | +| ---- | --- | +| Add | For adding an issue. Do not use `create` or `new` | +| View | View an issue | +| Edit | Edit an issue. Do not use `update` | +| Close | Closing an issue | +| Re-open | Re-open an issue. There should never be a need to use `open` as a verb | +| Delete | Deleting an issue. Do not use `remove` | \ No newline at end of file -- cgit v1.2.1 From cfabd5b5a9fb47b68210683c813efc36e9e1d921 Mon Sep 17 00:00:00 2001 From: Victor Wu Date: Wed, 16 Nov 2016 21:29:28 +0000 Subject: Update copy.md with issue guideline updates and merge request guidelines Update examples and labels to use sentence case. Update copy.md [ci skip] Update copy.md [ci skip] Update copy.md --- doc/development/ux_guide/copy.md | 73 ++++++++++++++++++++++++++-------------- 1 file changed, 47 insertions(+), 26 deletions(-) (limited to 'doc/development/ux_guide/copy.md') diff --git a/doc/development/ux_guide/copy.md b/doc/development/ux_guide/copy.md index 03392a003ee..227b4fd3451 100644 --- a/doc/development/ux_guide/copy.md +++ b/doc/development/ux_guide/copy.md @@ -7,7 +7,7 @@ We are currently inconsistent with this guidance. Images below are created to il ## Contents * [Brevity](#brevity) -* [Forms](#forms) +* [Sentence case](#sentence-case) * [Terminology](#terminology) --- @@ -27,52 +27,73 @@ Preferrably use context and placement of controls to make it obvious what clicki --- -## Forms +## Sentence case +Use sentence case for all titles, headings, labels, menu items, and buttons. -### Adding items +--- + +## Terminology +Only use the terms in the tables below. + +### Issues + +#### Adjectives (states) + +| Term | +| ---- | +| Open | +| Closed | +| Deleted | + +>**Example:** +Use `5 open issues` and don't use `5 pending issues`. + +#### Verbs (actions) + +| Term | Use | Don't | +| ---- | --- | --- | +| Add | Add an issue | Don't use `create` or `new` | +| View | View an open or closed issue || +| Edit | Edit an open or closed issue | Don't use `update` | +| Close | Close an open issue || +| 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 || + +#### Add issue When viewing a list of issues, there is a button that is labeled `Add`. Given the context in the example, it is clearly referring to issues. If the context were not clear enough, the label could be `Add issue`. Clicking the button will bring you to the `Add issue` form. Other add flows should be similar. ![Add issue button](img/copy-form-addissuebutton.png) -The form should be titled `Add issue`. The submit button should be labeled `Save` or `Submit`. Do not use `Add`, `Create`, `New`, or `Save Changes`. The cancel button should be labeled `Cancel`. Do not 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) -### Editing items +#### Edit issue When in context of an issue, the affordance to edit it is labeled `Edit`. If the context is not clear enough, `Edit issue` could be considered. Other edit flows should be similar. ![Edit issue button](img/copy-form-editissuebutton.png) -The form should be titled `Edit Issue`. The submit button should be labeled `Save`. Do not use `Edit`, `Update`, `New`, or `Save Changes`. The cancel button should be labeled `Cancel`. Do not 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) ---- - -## Terminology -### Issues +### Merge requests #### Adjectives (states) -| Term | Use | -| ---- | --- | -| Open | Issue is active | -| Closed | Issue is no longer active | - ->**Example:** -Use `5 open issues` and do not use `5 pending issues`. -Only use the adjectives in the table above. +| Term | +| ---- | +| Open | +| Merged | #### Verbs (actions) -| Term | Use | -| ---- | --- | -| Add | For adding an issue. Do not use `create` or `new` | -| View | View an issue | -| Edit | Edit an issue. Do not use `update` | -| Close | Closing an issue | -| Re-open | Re-open an issue. There should never be a need to use `open` as a verb | -| Delete | Deleting an issue. Do not use `remove` | \ No newline at end of file +| Term | Use | Don't | +| ---- | --- | --- | +| Add | Add a merge request | Do not use `create` or `new` | +| View | View an open or merged merge request || +| Edit | Edit an open or merged merge request| Do not use `update` | +| Merge | Merge an open merge request || \ No newline at end of file -- cgit v1.2.1 From 4a411f2711be742b41dc347a0fa876bd9576a0ab Mon Sep 17 00:00:00 2001 From: awhildy Date: Mon, 21 Nov 2016 11:44:21 -0800 Subject: [ci skip] Add Approve and Remove Approval to UX Guide terminology table --- doc/development/ux_guide/copy.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'doc/development/ux_guide/copy.md') diff --git a/doc/development/ux_guide/copy.md b/doc/development/ux_guide/copy.md index 227b4fd3451..b557fb47120 100644 --- a/doc/development/ux_guide/copy.md +++ b/doc/development/ux_guide/copy.md @@ -96,4 +96,6 @@ The form should be titled `Edit issue`. The submit button should be labeled `Sav | Add | Add a merge request | Do not use `create` or `new` | | View | View an open or merged merge request || | Edit | Edit an open or merged merge request| Do not use `update` | -| Merge | Merge an open merge request || \ No newline at end of file +| Approve | Approve an open merge request || +| Remove approval, unapproved | Remove approval of an open merge request | Do not use `unapprove` as that is not an English word| +| Merge | Merge an open merge request || -- cgit v1.2.1 From 30f050491694e27232ddab679785ddac2dd46514 Mon Sep 17 00:00:00 2001 From: awhildy Date: Sun, 27 Nov 2016 21:25:45 -0800 Subject: Create animation page and clean up index Add guidance on timings and easing [ci skip] Detail when not to use easing Add dropdown and hover examples Add quick update animation --- doc/development/ux_guide/copy.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'doc/development/ux_guide/copy.md') diff --git a/doc/development/ux_guide/copy.md b/doc/development/ux_guide/copy.md index b557fb47120..8896d450f14 100644 --- a/doc/development/ux_guide/copy.md +++ b/doc/development/ux_guide/copy.md @@ -1,6 +1,8 @@ # Copy -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 for GitLab is clear and direct. We strike a clear balance between professional and friendly. We can empathesize with users (such as celebrating completing all Todos), and remain respectful of the importance of the work. We are that trusted, friendly coworker that is helpful and understanding. + +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. >**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. -- cgit v1.2.1