update API docs, update copy

docs/development/core/public/kibana-plugin-core-public.doclinksstart.links.md

@@ -8,4 +8,4 @@
 
 ```typescript
 readonly links: DocLinks;
-```
+```

docs/development/core/public/kibana-plugin-core-public.doclinksstart.md

@@ -18,3 +18,4 @@ export interface DocLinksStart
 |  [DOC\_LINK\_VERSION](./kibana-plugin-core-public.doclinksstart.doc_link_version.md) | string |  |
 |  [ELASTIC\_WEBSITE\_URL](./kibana-plugin-core-public.doclinksstart.elastic_website_url.md) | string |  |
 |  [links](./kibana-plugin-core-public.doclinksstart.links.md) | DocLinks |  |
+

src/core/public/public.api.md

@@ -1592,4 +1592,4 @@ export interface UserProvidedValues<T = any> {
 //
 // src/core/public/core_system.ts:195:21 - (ae-forgotten-export) The symbol "InternalApplicationStart" needs to be exported by the entry point index.d.ts
 
-```
+```

x-pack/plugins/maps/public/connected_components/edit_layer_panel/join_editor/join_editor.tsx

@@ -11,7 +11,6 @@ import uuid from 'uuid/v4';
 import { EuiTitle, EuiSpacer, EuiTextAlign, EuiCallOut } from '@elastic/eui';
 
 import { FormattedMessage } from '@kbn/i18n-react';
-import { i18n } from '@kbn/i18n';
 import { Join } from './resources/join';
 import { JoinDocumentationPopover } from './resources/join_documentation_popover';
 import { IVectorLayer } from '../../../classes/layers/vector_layer';

x-pack/plugins/maps/public/connected_components/edit_layer_panel/join_editor/resources/join_documentation_popover.tsx

@@ -38,31 +38,39 @@ export class JoinDocumentationPopover extends Component<{}, State> {
           <p>
             <FormattedMessage
               id="xpack.maps.joinDocs.intro"
-              defaultMessage="A term join adds properties to vector features for data-driven styling."
+              defaultMessage="Term joins augment layers with properties for data driven styling. Term joins work as follows:"
             />
           </p>
+          <ul>
+            <li>
+              <FormattedMessage
+                id="xpack.maps.joinDocs.sharedKey"
+                defaultMessage="A shared key combines vector features, the left source, with the results of an Elasticsearch aggregation, the right source."
+              />
+            </li>
+            <li>
+              <FormattedMessage
+                id="xpack.maps.joinDocs.termsAggregation"
+                defaultMessage="The terms aggregation creates a bucket for each unique shared key."
+              />
+            </li>
+            <li>
+              <FormattedMessage
+                id="xpack.maps.joinDocs.metrics"
+                defaultMessage="Metrics are calculated for all documents in a bucket."
+              />
+            </li>
+            <li>
+              <FormattedMessage
+                id="xpack.maps.joinDocs.join"
+                defaultMessage="The join adds metrics for each terms aggregation bucket with the corresponding shared key."
+              />
+            </li>
+          </ul>
           <p>
             <FormattedMessage
-              id="xpack.maps.joinDocs.intro"
-              defaultMessage="A term join uses a shared key to combine vector features with the results of an Elasticsearch terms aggregation."
-            />
-          </p>
-          <p>
-            <FormattedMessage
-              id="xpack.maps.joinDocs.intro"
-              defaultMessage="The terms aggregation creates a bucket for each unique shared key. Metrics are calculated for all documents in a bucket."
-            />
-          </p>
-          <p>
-            <FormattedMessage
-              id="xpack.maps.joinDocs.intro"
-              defaultMessage="The join adds metrics for each terms aggregation bucket to the feature with the corresponding shared key. Features without a corresponding terms aggregation bucket are not visible on the map."
-            />
-          </p>
-          <p>
-            <FormattedMessage
-              id="xpack.maps.joinDocs.exmaple"
-              defaultMessage="For example, you can use a term join to add web log traffic count to world countries, then shade the countries by web log traffic."
+              id="xpack.maps.joinDocs.noMatches"
+              defaultMessage="Features that do have have a corresponding terms aggregation bucket are not visible on the map."
             />
           </p>
           <EuiLink href={getDocLinks().links.maps.termJoinsExample} target="_blank" external={true}>