diff --git a/common/changes/office-ui-fabric-react/jahnp-teachingbubble-usagedocs_2018-11-30-03-28.json b/common/changes/office-ui-fabric-react/jahnp-teachingbubble-usagedocs_2018-11-30-03-28.json new file mode 100644 index 00000000000000..cedb28254364db --- /dev/null +++ b/common/changes/office-ui-fabric-react/jahnp-teachingbubble-usagedocs_2018-11-30-03-28.json @@ -0,0 +1,11 @@ +{ + "changes": [ + { + "packageName": "office-ui-fabric-react", + "comment": "TeachingBubble: Expand usage documentation to distinguish it from similar components.", + "type": "patch" + } + ], + "packageName": "office-ui-fabric-react", + "email": "pejahn@microsoft.com" +} \ No newline at end of file diff --git a/packages/office-ui-fabric-react/src/components/TeachingBubble/TeachingBubble.doc.tsx b/packages/office-ui-fabric-react/src/components/TeachingBubble/TeachingBubble.doc.tsx index b890488375121f..9e2c6edf7edb28 100644 --- a/packages/office-ui-fabric-react/src/components/TeachingBubble/TeachingBubble.doc.tsx +++ b/packages/office-ui-fabric-react/src/components/TeachingBubble/TeachingBubble.doc.tsx @@ -49,6 +49,8 @@ export const TeachingBubblePageProps: IDocPageProps = { ], propertiesTablesSources: [require('!raw-loader!office-ui-fabric-react/src/components/TeachingBubble/TeachingBubble.types.ts')], overview: require('!raw-loader!office-ui-fabric-react/src/components/TeachingBubble/docs/TeachingBubbleOverview.md'), + dos: require('!raw-loader!office-ui-fabric-react/src/components/TeachingBubble/docs/TeachingBubbleDos.md'), + donts: require('!raw-loader!office-ui-fabric-react/src/components/TeachingBubble/docs/TeachingBubbleDonts.md'), isHeaderVisible: true, isFeedbackVisible: true }; diff --git a/packages/office-ui-fabric-react/src/components/TeachingBubble/docs/TeachingBubbleDonts.md b/packages/office-ui-fabric-react/src/components/TeachingBubble/docs/TeachingBubbleDonts.md new file mode 100644 index 00000000000000..3be316c2511d45 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/TeachingBubble/docs/TeachingBubbleDonts.md @@ -0,0 +1,4 @@ +- Don't use TeachingBubbles when a Callout would be sufficient. +- Don't use TeachingBubbles for user-invoked actions, such as clicking on a button or interacting with a UI element. +- Don't continue to show a TeachingBubble once it's been show to the user, even if they have not completed the desired action. +- Don't use TeachingBubbles for permanent parts of a UX. diff --git a/packages/office-ui-fabric-react/src/components/TeachingBubble/docs/TeachingBubbleDos.md b/packages/office-ui-fabric-react/src/components/TeachingBubble/docs/TeachingBubbleDos.md new file mode 100644 index 00000000000000..0cb687062bbc69 --- /dev/null +++ b/packages/office-ui-fabric-react/src/components/TeachingBubble/docs/TeachingBubbleDos.md @@ -0,0 +1,5 @@ +- Use TeachingBubbles to draw attention to new or important features. +- Use TeachingBubbles for actions invoked by the system, like a new capability being available. +- TeachingBubbles can be used in a sequence to illustrate a flow or series of features. +- Use TeachingBubbles for a limited time, usually while a feature is considered "new". +- Show one TeachingBubble at a time. diff --git a/packages/office-ui-fabric-react/src/components/TeachingBubble/docs/TeachingBubbleOverview.md b/packages/office-ui-fabric-react/src/components/TeachingBubble/docs/TeachingBubbleOverview.md index 3f69fd9d5b86b1..cbb04584923d81 100644 --- a/packages/office-ui-fabric-react/src/components/TeachingBubble/docs/TeachingBubbleOverview.md +++ b/packages/office-ui-fabric-react/src/components/TeachingBubble/docs/TeachingBubbleOverview.md @@ -1 +1,5 @@ -TeachingBubbles allow the user to display important hints on their web pages with a callout box. \ No newline at end of file +TeachingBubbles are a special kind of [Callout](#/components/callout) used to prominently display important hints to a specific part of a page. They should be used to educate the user about an element that may be easy to miss, such as a new feature or option in the UI. Because they increase engagement with a part of the UI, they are often paired with [Coachmarks](#/components/coachmark). + +TeachingBubbles are usually invoked by a system change rather than a user action, so they should generally not be used to show supplemental information or helper text. This is better suited for Callouts or [Tooltips](#/components/tooltip), which are used to simplify interactions. TeachingBubbles should be used to temporarily highlight a feature and should only be shown for a limited time; they should not be permanent parts of a UX. + +TeachingBubbles should otherwise follow the same usage guidance as Callouts. diff --git a/packages/office-ui-fabric-react/src/components/TeachingBubble/examples/TeachingBubble.WideIllustration.Example.tsx b/packages/office-ui-fabric-react/src/components/TeachingBubble/examples/TeachingBubble.WideIllustration.Example.tsx index 3470ea2d7c6e30..06fd774104b57e 100644 --- a/packages/office-ui-fabric-react/src/components/TeachingBubble/examples/TeachingBubble.WideIllustration.Example.tsx +++ b/packages/office-ui-fabric-react/src/components/TeachingBubble/examples/TeachingBubble.WideIllustration.Example.tsx @@ -24,7 +24,7 @@ export class TeachingBubbleWideIllustrationExample extends React.Component<{}, I public render(): JSX.Element { const { isTeachingBubbleVisible } = this.state; - const exampleImageProps: IImageProps = { src: 'http://placehold.it/364x140' }; + const exampleImageProps: IImageProps = { src: 'http://placehold.it/154x140' }; const examplePrimaryButton: IButtonProps = { children: 'Try it out' };