[Docs] Update and improve docs for Visualize and Discover (elastic#49810

) (elastic#51359) * [Docs] Update and improve docs for Visualize and Discover * Create a new section for default editor docs * Fix significant terms link * Writer changes * Remove pages that aren't helpful to users * More writer changes
mattkime · Nov 22, 2019 · 89ac6c9 · 89ac6c9
1 parent 16bc4f2
commit 89ac6c9
Show file tree

Hide file tree

Showing 51 changed files with 324 additions and 778 deletions.
diff --git a/docs/discover/context.asciidoc b/docs/discover/context.asciidoc
@@ -3,7 +3,7 @@
 
 For certain applications it can be useful to inspect a window of documents
 surrounding a specific event. The context view enables you to do just that for
-index patterns that are configured to contain time-based events.
+<<index-patterns, index patterns>> that are configured to contain time-based events.
 
 To show the context surrounding an anchor document, click the *Expand* button
 image:images/ExpandButton.jpg[Expand Button] to the left of the document's

diff --git a/docs/discover/document-data.asciidoc b/docs/discover/document-data.asciidoc
@@ -5,7 +5,7 @@ When you submit a search query, the 500 most recent documents that match the que
 are listed in the Documents table. You can configure the number of documents shown
 in the table by setting the `discover:sampleSize` property in <<advanced-options,
 Advanced Settings>>. By default, the table shows the localized version of the time
-field configured for the selected index pattern and the document `_source`. You can
+field configured for the selected <<index-patterns, index pattern>> and the document `_source`. You can
 <<adding-columns, add fields to the Documents table>> from the Fields list.
 You can <<sorting, sort the listed documents>> by any indexed field that's included
 in the table.

diff --git a/docs/discover/field-filter.asciidoc b/docs/discover/field-filter.asciidoc
@@ -14,7 +14,8 @@ To add a filter from the Fields list:
 . Click the name of the field you want to filter on. This displays the top
 five values for that field.
 +
-image::images/filter-field.jpg[]
+[role="screenshot"]
+image::images/filter-field.png[height=317]
 . To add a positive filter, click the *Positive Filter* button
 image:images/PositiveFilter.jpg[Positive Filter].
 This includes only those documents that contain that value in the field.
@@ -43,8 +44,7 @@ field name. This includes only those documents that contain the field.
 To manually add a filter:
 
 . Click *Add Filter*. A popup will be displayed for you to create the filter.
-+
-image::images/add_filter.png[]
+
 . Choose a field to filter by. This list of fields will include fields from the
 index pattern you are currently querying against.
 +
@@ -78,26 +78,26 @@ turn off the suggestions by setting the advanced setting, `filterEditor:suggestV
 [[filter-pinning]]
 === Managing Filters
 
-To modify a filter, hover over it and click one of the action buttons.
+To modify a filter, click on it and click one of the action buttons.
 
 image::images/filter-allbuttons.png[]
 
 &nbsp;
 
-image:images/filter-enable.png[] Enable Filter :: Disable the filter without
-removing it. Click again to reenable the filter. Diagonal stripes indicate
-that a filter is disabled.
-image:images/filter-pin.png[] Pin Filter :: Pin the filter. Pinned filters
+Pin across all apps :: Pinned filters
 persist when you switch contexts in Kibana. For example, you can pin a filter
 in Discover and it remains in place when you switch to Visualize.
 Note that a filter is based on a particular index field--if the indices being
 searched don't contain the field in a pinned filter, it has no effect.
-image:images/filter-toggle.png[] Invert Filter :: Switch from a positive
-filter to a negative filter and vice-versa.
-image:images/filter-delete.png[] Remove Filter :: Remove the filter.
-image:images/filter-custom.png[] Edit Filter :: <<filter-edit, Edit the
+Edit Filter :: <<filter-edit, Edit the
 filter>> definition.  Enables you to manually update the filter and
 specify a label for the filter.
+Exclude results :: Switch from a positive
+filter to a negative filter and vice-versa.
+Temporarily disable :: Disable the filter without
+removing it. Click again to reenable the filter. Diagonal stripes indicate
+that a filter is disabled.
+Remove Filter :: Remove the filter.
 
 To apply a filter action to all of the applied filters,
 click *Actions* and select the action.

diff --git a/docs/discover/search.asciidoc b/docs/discover/search.asciidoc
@@ -1,7 +1,7 @@
 [[search]]
 == Searching your data
-You can search the indices that match the current index pattern by entering
-your search criteria in the Query bar. By default you can use Kibana's standard query language
+You can search the indices that match the current <<index-patterns, index pattern>> by entering
+your search criteria in the Query bar. By default you can use Kibana's <<kuery-query, standard query language>>
 which features autocomplete and a simple, easy to use syntax. Kibana's legacy query
 language (based on Lucene https://lucene.apache.org/core/2_9_4/queryparsersyntax.html[query syntax])
 is still available for the time being under the options menu in the Query Bar. When this

diff --git a/docs/discover/set-time-filter.asciidoc b/docs/discover/set-time-filter.asciidoc
@@ -1,7 +1,7 @@
 [[set-time-filter]]
 == Setting the time filter
 If your index contains time-based events, and a time-field is configured for the 
-selected index pattern, set a time filter that displays only the data within the 
+selected <<index-patterns, index pattern>>, set a time filter that displays only the data within the
 specified time range.
 
 You can use the time filter to change the time range, or select a specific time 

diff --git a/docs/discover/viewing-field-stats.asciidoc b/docs/discover/viewing-field-stats.asciidoc
@@ -11,4 +11,4 @@ they are available in the side bar if we uncheck "Hide missing fields".
 
 To view field data statistics, click the name of a field in the Fields list.
 
-image:images/filter-field.jpg[Field Statistics]
+image:images/filter-field.png[Field Statistics,height=317]
diff --git a/docs/images/add-bucket.png b/docs/images/add-bucket.png
diff --git a/docs/images/add_filter.png b/docs/images/add_filter.png
diff --git a/docs/images/add_filter_field.png b/docs/images/add_filter_field.png
diff --git a/docs/images/add_filter_operator.png b/docs/images/add_filter_operator.png
diff --git a/docs/images/add_filter_value.png b/docs/images/add_filter_value.png
diff --git a/docs/images/bar-terms-agg.jpg b/docs/images/bar-terms-agg.jpg
diff --git a/docs/images/bar-terms-agg.png b/docs/images/bar-terms-agg.png
diff --git a/docs/images/bar-terms-subagg.jpg b/docs/images/bar-terms-subagg.jpg
diff --git a/docs/images/bar-terms-subagg.png b/docs/images/bar-terms-subagg.png
diff --git a/docs/images/color-picker.png b/docs/images/color-picker.png
diff --git a/docs/images/edit_filter_query.png b/docs/images/edit_filter_query.png
diff --git a/docs/images/edit_filter_query_json.png b/docs/images/edit_filter_query_json.png
diff --git a/docs/images/filter-allbuttons.png b/docs/images/filter-allbuttons.png
diff --git a/docs/images/filter-custom.png b/docs/images/filter-custom.png
diff --git a/docs/images/filter-delete.png b/docs/images/filter-delete.png
diff --git a/docs/images/filter-enable.png b/docs/images/filter-enable.png
diff --git a/docs/images/filter-field.jpg b/docs/images/filter-field.jpg
diff --git a/docs/images/filter-field.png b/docs/images/filter-field.png
diff --git a/docs/images/filter-pin.png b/docs/images/filter-pin.png
diff --git a/docs/images/filter-toggle.png b/docs/images/filter-toggle.png
diff --git a/docs/images/gauge.png b/docs/images/gauge.png
diff --git a/docs/images/goal.png b/docs/images/goal.png
diff --git a/docs/images/visualize-date-histogram-split-1.png b/docs/images/visualize-date-histogram-split-1.png
diff --git a/docs/images/visualize-date-histogram-split-2.png b/docs/images/visualize-date-histogram-split-2.png
diff --git a/docs/images/visualize-date-histogram.png b/docs/images/visualize-date-histogram.png
diff --git a/docs/images/visualize-drag-reorder.png b/docs/images/visualize-drag-reorder.png
diff --git a/docs/user/discover.asciidoc b/docs/user/discover.asciidoc
@@ -4,7 +4,7 @@
 [partintro]
 --
 *Discover* enables you to explore your data with {kib}'s data discovery functions. 
-You have access to every document in every index that matches the selected index pattern. 
+You have access to every document in every index that matches the selected <<index-patterns, index pattern>>.
 You can submit search queries, filter the search results, and view document data.
 You can also see the number of documents that match the search query and get field value statistics. 
 If a time field is configured for the selected index pattern, the distribution of 

diff --git a/docs/user/visualize.asciidoc b/docs/user/visualize.asciidoc
@@ -3,58 +3,49 @@
 
 [partintro]
 --
-_Visualize_ enables you to create visualizations of the data in your
-Elasticsearch indices. You can then build <<dashboard, dashboards>> that
-display related visualizations.
+_Visualize_ enables you to create visualizations of the data from your Elasticsearch indices, which you can then add to dashboards for analysis.
 
-Kibana visualizations are based on Elasticsearch queries. By using a
-series of Elasticsearch {ref}/search-aggregations.html[aggregations]
-to extract and process your data, you can create charts that show
-you the trends, spikes, and dips you need to know about.
+{kib} visualizations are based on Elasticsearch queries. By using a series of {es} {ref}/search-aggregations.html[aggregations] to extract and process your data, you can create charts that show you the trends, spikes, and dips you need to know about.
 
-You can create visualizations from a search saved from <<discover, Discover>>
-or start with a new search query.
---
-
-[[createvis]]
-== Creating a Visualization
+[float]
+[[create-a-visualization]]
+== Create visualizations
 
-To create a visualization:
-
-. Click on *Visualize* in the side navigation.
-. Click the *Create new visualization* button or the **+** button.
+. Open *Visualize*.
+. Click *Create new visualization*.
 . Choose the visualization type:
-
++
 * *Basic charts*
-[horizontal]
 <<lens,Lens>>:: Quickly build several types of basic visualizations by simply dragging and dropping the data fields you want to display.
-<<xy-chart,Line&comma; Area and Bar charts>>:: Compare different series in X/Y charts.
-<<heatmap-chart,Heat maps>>:: Shade cells within a matrix.
-<<pie-chart,Pie chart>>:: Display each source's contribution to a total.
-* *Data*
+* *<<most-frequent,Most frequently used visualizations>>*
+[horizontal]
+Line&comma; area, and bar charts:: Compare different series in X/Y charts.
+Pie chart:: Display each source contribution to a total.
+Data table:: Flattens aggregations into table format.
+Metric:: Display a single number.
+Goal and gauge:: Display a number with progress indicators.
+Heat maps:: Display shaded cells within a matrix.
+Tag cloud:: Display words in a cloud, where the size of the word corresponds to its importance.
+* *Time series optimized*
 [horizontal]
-<<data-table,Data table>>:: Display the raw data of a composed aggregation.
-<<metric-chart,Metric>>:: Display a single number.
-<<goal-chart,Goal and Gauge>>:: Display a gauge.
+<<TSVB,TSVB>>:: Visualize time series data using pipeline aggregations.
+<<timelion,Timelion>>:: Compute and combine data from multiple time series
+data sets.
 * *Maps*
 [horizontal]
-<<tilemap,Coordinate map>>:: Associate the results of an aggregation with geographic locations.
-<<regionmap,Region map>>:: Thematic maps where a shape's color intensity corresponds to a metric's value.
-locations.
-* *Time Series*
+<<maps, Elastic maps>>:: The most powerful way of visualizing map data in {kib}.
+<<tilemap,_Coordinate map_>>:: Displays points on a map using a geohash aggregation.
+<<regionmap,_Region map_>>:: Merge any structured map data onto a shape.
+* *<<for-dashboard, For use in dashboards>>*
 [horizontal]
-<<time-series-intro,Timelion>>:: Compute and combine data from multiple time series
-data sets.
-<<TSVB,TSVB>>:: Visualize time series data using pipeline aggregations.
-* *Other*
+<<for-dashboard,Controls>>:: Provides the ability to add interactive inputs to a Dashboard.
+<<for-dashboard,Markdown widget>>:: Display free-form information or instructions.
+* *For developers*
 [horizontal]
-<<controls,Controls>>:: Controls provide the ability to add interactive inputs to Kibana Dashboards.
-<<markdown-widget,Markdown widget>>:: Display free-form information or
-instructions.
-<<tagcloud-chart,Tag cloud>>:: Display words as a cloud in which the size of the word correspond to its importance.
-<<vega-graph,Vega graph>>:: Support for user-defined graphs, external data sources, images, and user-defined interactivity.
+<<vega-graph,Vega>>:: Complete control over query and display.
+
 . Specify a search query to retrieve the data for your visualization:
-** To enter new search criteria, select the index pattern for the indices that
+** To enter new search criteria, select the <<index-patterns, index pattern>> for the indices that
 contain the data you want to visualize. This opens the visualization builder
 with a wildcard query that matches all of the documents in the selected
 indices.
@@ -67,110 +58,23 @@ modifications to the saved search are automatically reflected in the
 visualization. To disable automatic updates, you can disconnect a visualization
 from the saved search.
 
-. In the visualization builder, choose the metric aggregation for the
-visualization's Y axis:
-
-* *Metric Aggregations*:
-
-* {ref}/search-aggregations-metrics-valuecount-aggregation.html[count]
-* {ref}/search-aggregations-metrics-avg-aggregation.html[average]
-* {ref}/search-aggregations-metrics-sum-aggregation.html[sum]
-* {ref}/search-aggregations-metrics-min-aggregation.html[min]
-* {ref}/search-aggregations-metrics-max-aggregation.html[max]
-* {ref}/search-aggregations-metrics-stats-aggregation.html[standard deviation]
-* {ref}/search-aggregations-metrics-cardinality-aggregation.html[unique count]
-* {ref}/search-aggregations-metrics-percentile-aggregation.html[median] (50th percentile)
-* {ref}/search-aggregations-metrics-percentile-aggregation.html[percentiles]
-* {ref}/search-aggregations-metrics-percentile-rank-aggregation.html[percentile ranks]
-* {ref}/search-aggregations-metrics-top-hits-aggregation.html[top hit]
-* {ref}/search-aggregations-metrics-geocentroid-aggregation.html[geo centroid]
-
-
-* *Parent Pipeline Aggregations*:
-
-* {ref}/search-aggregations-pipeline-derivative-aggregation.html[derivative]
-* {ref}/search-aggregations-pipeline-cumulative-sum-aggregation.html[cumulative sum]
-* {ref}/search-aggregations-pipeline-movavg-aggregation.html[moving average]
-* {ref}/search-aggregations-pipeline-serialdiff-aggregation.html[serial diff]
-
-
-* *Sibling Pipeline Aggregations*:
-
-* {ref}/search-aggregations-pipeline-avg-bucket-aggregation.html[average bucket]
-* {ref}/search-aggregations-pipeline-sum-bucket-aggregation.html[sum bucket]
-* {ref}/search-aggregations-pipeline-min-bucket-aggregation.html[min bucket]
-* {ref}/search-aggregations-pipeline-max-bucket-aggregation.html[max bucket]
-
-
-. For the visualizations X axis, select a bucket aggregation:
-+
-* {ref}/search-aggregations-bucket-datehistogram-aggregation.html[date histogram]
-* {ref}/search-aggregations-bucket-range-aggregation.html[range]
-* {ref}/search-aggregations-bucket-terms-aggregation.html[terms]
-* {ref}/search-aggregations-bucket-filters-aggregation.html[filters]
-* {ref}/search-aggregations-bucket-significantterms-aggregation.html[significant terms]
-
-For example, if you're indexing Apache server logs, you could build bar chart
-that shows the distribution of incoming requests by geographic location by
-specifying a terms aggregation on the `geo.src` field:
-
-image::images/bar-terms-agg.jpg[]
-
-The y-axis shows the number of requests received from each country, and the
-countries are displayed across the x-axis.
-
-Bar, line, or area chart visualizations use _metrics_ for the y-axis and
-_buckets_ for the x-axis. Buckets are analogous to SQL `GROUP BY`
-statements. Pie charts, use the metric for the slice size and the bucket
-for the number of slices.
-
-You can further break down the data by specifying sub aggregations. The first
-aggregation determines the data set for any subsequent aggregations. Sub
-aggregations are applied in order--you can drag the aggregations to change the
-order in which they're applied.
-
-For example, you could add a terms sub aggregation on the `geo.dest` field to
-the Country of Origin bar chart to see the locations those requests were
-targeting.
-
-image::images/bar-terms-subagg.jpg[]
-
-For more information about working with sub aggregations, see
-https://www.elastic.co/blog/kibana-aggregation-execution-order-and-you[Kibana,
-Aggregation Execution Order, and You].
-
-include::{kib-repo-dir}/visualize/saving.asciidoc[]
-
+--
 include::{kib-repo-dir}/visualize/visualize_rollup_data.asciidoc[]
 
 include::{kib-repo-dir}/visualize/lens.asciidoc[]
 
-include::{kib-repo-dir}/visualize/xychart.asciidoc[]
-
-include::{kib-repo-dir}/visualize/controls.asciidoc[]
-
-include::{kib-repo-dir}/visualize/datatable.asciidoc[]
-
-include::{kib-repo-dir}/visualize/markdown.asciidoc[]
+include::{kib-repo-dir}/visualize/most-frequent.asciidoc[]
 
-include::{kib-repo-dir}/visualize/metric.asciidoc[]
-
-include::{kib-repo-dir}/visualize/goal.asciidoc[]
-
-include::{kib-repo-dir}/visualize/pie.asciidoc[]
+include::{kib-repo-dir}/visualize/tsvb.asciidoc[]
+include::{kib-repo-dir}/visualize/timelion.asciidoc[]
 
 include::{kib-repo-dir}/visualize/tilemap.asciidoc[]
-
 include::{kib-repo-dir}/visualize/regionmap.asciidoc[]
 
-include::{kib-repo-dir}/visualize/timelion.asciidoc[]
-
-include::{kib-repo-dir}/visualize/tsvb.asciidoc[]
-
-include::{kib-repo-dir}/visualize/tagcloud.asciidoc[]
-
-include::{kib-repo-dir}/visualize/heatmap.asciidoc[]
+include::{kib-repo-dir}/visualize/for-dashboard.asciidoc[]
 
 include::{kib-repo-dir}/visualize/vega.asciidoc[]
 
+include::{kib-repo-dir}/visualize/saving.asciidoc[]
+
 include::{kib-repo-dir}/visualize/inspector.asciidoc[]
Original file line number	Diff line number	Diff line change
Expand Up		@@ -11,4 +11,4 @@ they are available in the side bar if we uncheck "Hide missing fields".

		To view field data statistics, click the name of a field in the Fields list.

		image:images/filter-field.jpg[Field Statistics]
		image:images/filter-field.png[Field Statistics,height=317]