Improve structure of toast docs.

src/ui/public/notify/toasts/TOAST_NOTIFICATIONS.md

@@ -8,68 +8,45 @@ Use this service to surface toasts in the bottom-right corner of the screen. Aft
 import { toastNotifications } from 'ui/notify';
 ```
 
-## Adding a toast
+## Interface
 
-The simplest way to display a toast is to call `add` and pass in a string. This will display the string as the title of the toast, and give the toast a neutral appearance.
+### Adding toasts
 
-```js
-toastNotifications.add('Saved document');
-```
-
-You can provide an object to configure the toast further. The properties of this object correspond to the `propTypes` accepted by the `EuiToast` component. Refer to [the EUI docs](elastic.github.io/eui/) for info on these `propTypes`.
+For convenience, there are several methods which predefine the appearance of different types of toasts. Use these methods so that the same types of toasts look similar to the user.
 
-```js
-toastNotifications.add({
-  title: 'Saved document',
-  text: 'Only you have access to this document',
-  color: 'success',
-  iconType: 'check',
-  'data-test-subj': 'saveDocumentSuccess',
-});
-```
+#### Default
 
-Because the underlying components are React, you can use JSX to pass in React elements to the `text` prop. This gives you total flexibility over the content displayed within the toast.
+Neutral toast. Tell the user a change in state has occurred, which is not necessarily good or bad.
 
 ```js
-toastNotifications.add({
-  title: 'Saved document',
-  text: (
-    <div>
-      <p>
-        Only you have access to this document. <a href="/documents">Edit permissions.</a>
-      </p>
-
-      <button onClick={() => deleteDocument()}}>
-        Delete document
-      </button>
-    </div>
-  ),
-});
+toastNotifications.add('Copied to clipboard');
 ```
 
-## Adding different types of toasts
-
-For convenience, there are several methods which predefine the appearance of different types of toasts. Use these methods so that the same types of toasts look similar to the user.
+#### Success
 
 Let the user know that an action was successful, such as saving or deleting an object.
 
 ```js
 toastNotifications.addSuccess('Saved document');
 ```
 
+#### Warning
+
 If something OK or good happened, but perhaps wasn't perfect, show a warning toast.
 
 ```js
 toastNotifications.addWarning('Saved document, but not edit history');
 ```
 
+#### Danger
+
 When the user initiated an action but the action failed, show them a danger toast.
 
 ```js
 toastNotifications.addDanger('An error caused your document to be lost');
 ```
 
-## Removing a toast
+### Removing a toast
 
 Toasts will automatically be dismissed after a brief delay, but if for some reason you want to dismiss a toast, you can use the returned toast from one of the `add` methods and then pass it to `remove`.
 
@@ -78,6 +55,39 @@ const toast = toastNotifications.add('Saved document');
 toastNotifications.remove(toast);
 ```
 
+### Configuration options
+
+If you want to configure the toast further you can provide an object instead of a string. The properties of this object correspond to the `propTypes` accepted by the `EuiToast` component. Refer to [the EUI docs](elastic.github.io/eui/) for info on these `propTypes`.
+
+```js
+toastNotifications.add({
+  title: 'Saved document',
+  text: 'Only you have access to this document',
+  color: 'success',
+  iconType: 'check',
+  'data-test-subj': 'saveDocumentSuccess',
+});
+```
+
+Because the underlying components are React, you can use JSX to pass in React elements to the `text` prop. This gives you total flexibility over the content displayed within the toast.
+
+```js
+toastNotifications.add({
+  title: 'Saved document',
+  text: (
+    <div>
+      <p>
+        Only you have access to this document. <a href="/documents">Edit permissions.</a>
+      </p>
+
+      <button onClick={() => deleteDocument()}}>
+        Delete document
+      </button>
+    </div>
+  ),
+});
+```
+
 ## Use in functional tests
 
 Functional tests are commonly used to verify that a user action yielded a sucessful outcome. if you surface a toast to notify the user of this successful outcome, you can place a `data-test-subj` attribute on the toast and use it to check if the toast exists inside of your functional test. This acts as a proxy for verifying the sucessful outcome.