Improve TeachingBubble usage docs

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": "[email protected]"
+}

packages/office-ui-fabric-react/src/components/TeachingBubble/TeachingBubble.doc.tsx

@@ -49,6 +49,8 @@ export const TeachingBubblePageProps: IDocPageProps = {
   ],
   propertiesTablesSources: [require<string>('!raw-loader!office-ui-fabric-react/src/components/TeachingBubble/TeachingBubble.types.ts')],
   overview: require<string>('!raw-loader!office-ui-fabric-react/src/components/TeachingBubble/docs/TeachingBubbleOverview.md'),
+  dos: require<string>('!raw-loader!office-ui-fabric-react/src/components/TeachingBubble/docs/TeachingBubbleDos.md'),
+  donts: require<string>('!raw-loader!office-ui-fabric-react/src/components/TeachingBubble/docs/TeachingBubbleDonts.md'),
   isHeaderVisible: true,
   isFeedbackVisible: true
 };

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.

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.

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.
+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.

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'
     };