Added designer notes content in markdown to most components. #1123

benwilsonsage · 2017-03-07T14:14:51Z

Added designer notes content in markdown to most components on the Carbon demo site.

Added designer notes content in markdown to most components.

chrisbarber86 · 2017-03-07T19:05:57Z

src/components/alert/definition.js

@@ -3,6 +3,19 @@ import OptionsHelper from '../../utils/helpers/options-helper';
 import Definition from './../../../demo/utils/definition';

 let definition = new Definition('alert', Alert, {
+  description: `I can see very important error or warning message interrupts my activity, but I can dismiss it when I choose.`,


Not sure this reads too well.

Series of typos - will correct.

andrewjtait · 2017-03-10T10:32:14Z

src/components/button/definition.js

@@ -3,6 +3,19 @@ import OptionsHelper from '../../utils/helpers/options-helper';
 import Definition from './../../../demo/utils/definition';

 let definition = new Definition('button', Button, {
+  description: `I can take a positive or negative action.`,


Is the use of this so polar? Isn't there scope for buttons which are neither positive or negative?

Will reword to generic.

andrewjtait · 2017-03-10T10:33:48Z

src/components/flash/definition.js

@@ -3,6 +3,17 @@ import Definition from './../../../demo/utils/definition';
 import OptionsHelper from './../../utils/helpers/options-helper';

 let definition = new Definition('flash', Flash, {
+  description: `I can see a simple positive or negative confirmation of an action which disappears quickly.`,


error messages don't disappear automatically - they persist

Reworded to make clear

andrewjtait · 2017-03-10T10:35:35Z

src/components/tabs/definition.js

@@ -4,6 +4,20 @@ import OptionsHelper from '../../utils/helpers/options-helper';
 import tabDefinition from './tab/definition';

 let definition = new Definition('tabs', Tabs, {
+  description: `I can quickly view variants of a page or filter Table content.`,


filter Table content? I think that is a bit misleading - you may be thinking of an area where we render different Tables in each Tab.

Reworded to clarify.

Minor content updates in response to feedback.

benwilsonsage · 2017-03-10T12:16:31Z

Updated content in response to reviewer comments - thank you.

Changes addressed

kylemayne

Hi @benwilsonsage. Nice work on these! I'm still working my way through but the majority of points are small.

I'd recommend pulling the branch down and looking at the designer notes in place (if you haven't already).

@andrewjtait @toni-leigh can we undertake some styling work around the designer notes section? I'll catch-up with you tomorrow about what we need to do.

kylemayne · 2017-03-14T16:26:03Z

src/components/alert/definition.js

+* __Longer, time sensitive message that must be dismissed?__ Try Toast.
+* __Confirm or cancel an action I’ve initiated?__ Try Confirm.
+* __Simple task in context?__ Try Dialog.
+  `,


Would you expect the 'try' to be a link?

added links in markdown throughout

kylemayne · 2017-03-14T16:34:13Z

src/components/button/definition.js

+* __Range of buttons where one is more important?__ Try Split Button.
+* __Range of buttons all of the same importance?__ Try Multi Action Button.
+* __Choosing one option from a highly visible range?__ Try Button Toggle.
+ `,


We viewing the build there appears to be random line breaks. Is this intentional?

Checked and removed any stray invisible characters.

kylemayne · 2017-03-14T16:40:41Z

src/components/button-toggle/definition.js

+* __Choosing one option from a very long list?__ Try Dropdown.
+* __Choosing more than one option?__ Try Checkbox.
+* __Icons.__
+ `,


Random line breaks when viewing the build.

Checked and removed invisible chars

kylemayne · 2017-03-14T16:42:22Z

src/components/button-toggle/definition.js

+* __Performing a single action?__ Try Button.
+* __Range of buttons where one is more important?__ Try Split Button.
+* __Range of buttons of the same importance?__ Try Multi Action Button.
+* __Choosing one option from a longer list?__ Try Radio Button.


Is it worth putting specific numbers on these for guidance?

added guidance in the text of each individual component.

kylemayne · 2017-03-14T16:45:33Z

src/components/alert/definition.js

@@ -3,6 +3,19 @@ import OptionsHelper from '../../utils/helpers/options-helper';
 import Definition from './../../../demo/utils/definition';

 let definition = new Definition('alert', Alert, {
+  description: `An important message interrupts my activity, but I can dismiss it when I choose.`,


What's your reason for writing descriptions in the first person?

It feels slightly different to the rest of the content. Maybe we should be mindful of the context, and be specific about what the component is?

Here's some examples from similar sites for a button as reference:
http://getbootstrap.com/components/#btn-dropdowns
https://material.io/guidelines/components/buttons.html
http://blueprintjs.com/docs/#components.button

Reworded out of the first person - the idea was to put the user's perspective first, but I see it's out of precedent with similar sites.

kylemayne · 2017-03-14T17:30:05Z

src/components/flash/definition.js

+* __Longer message which stays on-screen?__ Try Message.
+* __Longer, time sensitive message that must be dismissed?__ Try Toast.
+* __Error or warning message that interrupts activity?__ Try Alert.
+ `,


Line breaks:

checked and removed

kylemayne · 2017-03-14T17:32:47Z

src/components/form/definition.js

+* Try to create a single path to completion with your inputs, and between your inputs and the primary action Button - there’s good evidence users complete forms faster like this.
+* If an input is read-only, remove the field border so it appears as static text.
+* You can disable components in forms, but try to avoid this. If you need to, make it clear what the user needs to do, in order to activate the component.
+* Indicate mandatory, or optional fields, whichever is the minority. Think carefully before collecting optional data - don’t collect information you don’t need! Try suffixing ‘(optional)’ after your field label.


Should we duplicate content if it appears on child components?

The general advice on forms only appears for Form and Fieldset, not the sub-components. Disabling is mentioned in a few places for text inputs as that tends to happen a lot.

kylemayne · 2017-03-14T17:33:15Z

src/components/form/definition.js

+* More guidance is available for each of the individual inputs you might place inside this component.
+
+* __Editing a number of closely related inputs?__ Try Fieldset.
+ `,


Line break:

checked and removed

kylemayne · 2017-03-14T17:34:18Z

src/components/help/definition.js

+
+* __Tooltip hovering on any Carbon icon?__ Try Icon.
+* __Tooltip hovering on any component?__ Try Tooltip.
+ `,


Line break styling:

checked and removed

kylemayne · 2017-03-14T17:35:12Z

src/components/link/definition.js

+* To make the meaning of a link clearer, you can add an icon before it. Just name one of the Carbon icons.
+* Make your link names meaningful - for example, instead of ‘Click here’, try ‘Download Invoice 001’.
+* WCAG guidelines recommend that Color is not used as the only visual means of conveying information, indicating an action. Carbon applies bold weight, but you could also use text decoration.
+


Line breaks:

checked and removed

SeanArmstrong · 2017-03-20T11:16:23Z

@benwilsonsage @kylemayne the random line breaks occur due to added paragraphs in the markup shown here - markedjs/marked#663

This is caused by only adding one empty line to break up the lists. Simple fix is to add a second empty line. I can add these changes to the PR but it will likely hide most of the other comments related to grammar/sentencing etc so you may want to add them as you are addressing the other comments.

Let me know if you need some more info.

Reworded out of the first person.

…esigner-notes

Including wording updates, adding cross-reference links, and h3s throughout.

Removed file committed in error.

SeanArmstrong · 2017-03-23T14:19:38Z

src/components/create/definition.js

+* __Editing a number of closely related inputs?__ [Try Fieldset](/components/fieldset).
+* __Filling in a broad series of inputs?__ [Try Form](/components/form).
+* __Viewing content that’s grouped together visually?__ [Try Pod](/components/pod).
+* __Using Fieldset and Pod components together?__ [Try Show/Edit Pod.


This should be [Try Show/Edit Pod](/components/show-edit-pod)

SeanArmstrong · 2017-03-23T14:21:22Z

src/components/portrait/definition.js

+  designerNotes: `
+* Useful to represent a person, user, or organisation, similar to an avatar.
+* Use initials rather than an icon if you prefer.
+


This needs another empty line

Content adjusted.

SeanArmstrong · 2017-03-23T14:21:37Z

src/components/profile/definition.js

+  designerNotes: `
+* Useful to represent a person, user, or organisation, similar to an avatar.
+* The user is initially represented with their initials, but hovering on the initials can reveal an image. This helps to avoid distracting the user.
+


This needs another empty line

Content adjusted.

Missing designer notes added. Minor content updates and corrections.

SeanArmstrong · 2017-03-24T08:29:16Z

Done some QA over each page to ensure correct formatting. All seems fine. I think this is good to go unless @kylemayne spots any changes he would like to make

Add styling to designer notes

Added designer notes content in markdown to most components.

ee0d0dc

Added designer notes content in markdown to most components.

benwilsonsage requested review from andrewjtait and kylemayne March 7, 2017 14:15

benwilsonsage assigned andrewjtait Mar 7, 2017

chrisbarber86 reviewed Mar 7, 2017

View reviewed changes

andrewjtait previously requested changes Mar 10, 2017

View reviewed changes

andrewjtait added Pending QA Pending Review labels Mar 10, 2017

benwilsonsage added 2 commits March 10, 2017 12:15

Minor content updates in response to feedback.

fa51d6a

Minor content updates in response to feedback.

Merge branch 'master' into bens-designer-notes

e493373

benwilsonsage added 2 commits March 10, 2017 12:18

Merge branch 'master' into bens-designer-notes

facb881

Merge branch 'master' into bens-designer-notes

db47fc9

andrewjtait approved these changes Mar 14, 2017

View reviewed changes

andrewjtait added the Passed Review label Mar 14, 2017

kylemayne suggested changes Mar 14, 2017

View reviewed changes

Merge branch 'master' into bens-designer-notes

b8ec250

andrewjtait added this to the v1.0.0 milestone Mar 16, 2017

benwilsonsage added 5 commits March 23, 2017 11:20

Reworded out of the first person.

c9475ad

Reworded out of the first person.

Merge remote-tracking branch 'origin/bens-designer-notes' into bens-d…

7ea0a1a

…esigner-notes

Merge branch 'master' into bens-designer-notes

0a0a415

Minor content amendments

12abea9

Including wording updates, adding cross-reference links, and h3s throughout.

Removed file committed in error.

fac881d

Removed file committed in error.

SeanArmstrong reviewed Mar 23, 2017

View reviewed changes

Missing designer notes added. Minor content updates and corrections.

05ae01d

Missing designer notes added. Minor content updates and corrections.

SeanArmstrong added the Passed QA label Mar 24, 2017

SeanArmstrong removed the Pending QA label Mar 24, 2017

SeanArmstrong and others added 4 commits March 24, 2017 13:55

add styling to designer notes

60820bf

Merge pull request #1150 from Sage/information-styles

a051d80

Add styling to designer notes

add related components to its own section

c0d9a14

Amended markdown & created new related components section

206e474

kylemayne approved these changes Apr 3, 2017

View reviewed changes

kylemayne added Passed Review (2/2) and removed Pending Review labels Apr 3, 2017

kylemayne added 3 commits April 3, 2017 16:48

Merge branch 'master' into bens-designer-notes

69350a3

Copy change - removed inventory

57753d5

Merge branch 'master' into bens-designer-notes

379e43d

chrisbarber86 approved these changes Apr 4, 2017

View reviewed changes

SeanArmstrong merged commit 38ef78d into master Apr 4, 2017

SeanArmstrong deleted the bens-designer-notes branch April 4, 2017 10:35

Added designer notes content in markdown to most components. #1123

Added designer notes content in markdown to most components. #1123

Uh oh!

Conversation

benwilsonsage commented Mar 7, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

benwilsonsage commented Mar 10, 2017

Uh oh!

kylemayne left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kylemayne Mar 14, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

SeanArmstrong commented Mar 20, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

SeanArmstrong Mar 23, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kylemayne Mar 14, 2017 •

edited

Loading

SeanArmstrong commented Mar 20, 2017 •

edited

Loading

SeanArmstrong Mar 23, 2017 •

edited

Loading