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": "pejahn@microsoft.com"
+}

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,3 @@
+- Don't use TeachingBubbles for user-invoked actions.
+- Don't use TeachingBubbles when a Callout would be sufficient.
+- Don't show a TeachingBubble more than once, even if the user has not completed the action.

packages/office-ui-fabric-react/src/components/TeachingBubble/docs/TeachingBubbleDos.md

@@ -0,0 +1 @@
+- 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).
+
+Because they are usually invoked by a system change rather than a user action, TeachingBubbles 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 existing interactions.
+
+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'
     };