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

wylieconlon · 2019-10-30T22:35:12Z

The biggest change here is to create a new grouping of "Most frequently used visualizations" which share the same logic for being able to create aggregations. We call this the default editor, and because it's shared it makes sense to document the editor in one way and only document exceptions to the rule as needed.

The other changes made in this PR:

Removes all documentation that explains elements of the UI without context. This simplifies the documentation significantly.
Update screenshots for Discover which have not been updated since 6.0.0
Cross-links to the index pattern documentation in the first reference per page because users have been confused about the concept of an "index pattern"
Remove redundant wording on some aggregations such as the Min/max/average/sum aggregations
Groups maps and time-series visualizations better, specifically trying to highlight how Timelion is no longer shown by default, and how Coordinate Maps and Region Maps are visible in OSS by default but not in x-pack
Merges markdown and controls into one page and added "For use in dashboard" context
Explains how to use the Include/Exclude options on terms, in particular clarifying Exclude filter in aggregations only supports syntax for strings #12421

Updated pages:

http://kibana_49810.docs-preview.app.elstc.co/guide/en/kibana/master/field-filter.html
http://kibana_49810.docs-preview.app.elstc.co/guide/en/kibana/master/visualize.html

[skip ci]

Closes #12573

elasticmachine · 2019-10-30T22:35:14Z

Pinging @elastic/kibana-docs (Team:Docs)

elasticmachine · 2019-10-30T22:35:16Z

Pinging @elastic/kibana-app (Team:KibanaApp)

elasticmachine · 2019-10-30T23:45:53Z

💚 Build Succeeded

continuous-integration/kibana-ci/pull-request
Commit: e3e8fbc

elasticmachine · 2019-10-31T19:22:37Z

💚 Build Succeeded

continuous-integration/kibana-ci/pull-request
Commit: 1ae9ef3

elasticmachine · 2019-10-31T19:45:55Z

💚 Build Succeeded

continuous-integration/kibana-ci/pull-request
Commit: 610253e

gchaps

I reviewed the Discover section. Kaarina is reviewing Visualize.

There are also some old screenshots in document.context.asciidoc. Would you mind updating those screenshots as well?

docs/discover/field-filter.asciidoc

KOTungseth

This is a great PR! Thank you so much for making these changes. I'm about half way through on my own changes. I will pick this up again very soon.

docs/user/visualize.asciidoc

KOTungseth · 2019-10-31T19:49:46Z

docs/visualize/aggregations.asciidoc

@@ -0,0 +1,101 @@
+[[supported-aggregations]]
+=== Supported aggregations


Just to clarify, placing Supported aggregations here means that TSVB, Timelion, Coordinate Maps, Region Maps, Markdown and Dashboard controls, and Vega do not use these aggregations.

Is that right?

That is correct. Coordinate maps and region maps actually do use a subset of these, but those visualizations are now hidden by default in the basic license in 7.5

KOTungseth · 2019-10-31T19:57:08Z

docs/visualize/aggregations.asciidoc

+aggregation.
+* Top Hit: Uses the {ref}/search-aggregations-metrics-top-hits-aggregation.html[_top hits_]
+aggregation to return a sample of individual documents. If more than one document is matched by this aggregation, you must choose a technique for combining the values. These techniques are average, min, max, and sum.
+* Percentiles: The {ref}/search-aggregations-metrics-percentile-aggregation.html[_percentile_] aggregation divides the


I would use the same formatting as the previous bullet.

KOTungseth · 2019-10-31T19:59:17Z

docs/visualize/aggregations.asciidoc

+All of these visualizations support:
+
+**Metric Aggregations:**
+


What are metric aggregations?

KOTungseth · 2019-10-31T20:02:22Z

docs/visualize/aggregations.asciidoc

+*Max Bucket*:: The {ref}/search-aggregations-pipeline-avg-bucket-aggregation.html[_max bucket_]calculates the maximum value of a specified metric in a sibling aggregation
+
+**Bucket Aggregations:**
+


What are bucket aggregations?

I didn't want to redefine every term here, but this is an Elasticsearch term that we use throughout the Visualize apps https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket.html

I agree that we shouldn't double-document the definition, but does bucket aggregation mean the same thing in Elasticsearch as it does in Kibana?

They have the same meaning and we use the same words in both places (with few exceptions such as Unique Count)

docs/visualize/metric.asciidoc

docs/visualize/most-frequent.asciidoc

docs/visualize/aggregations.asciidoc

KOTungseth · 2019-10-31T21:23:36Z

docs/visualize/aggregations.asciidoc

+* Top Hit: Uses the {ref}/search-aggregations-metrics-top-hits-aggregation.html[_top hits_]
+aggregation to return a sample of individual documents. If more than one document is matched by this aggregation, you must choose a technique for combining the values. These techniques are average, min, max, and sum.
+* Percentiles: The {ref}/search-aggregations-metrics-percentile-aggregation.html[_percentile_] aggregation divides the
+values in a numeric field into percentile bands that you specify. Select a field from the drop-down, then specify one


Is it necessary to keep the task content in these definitions? I think we can remove Select a field from the drop-down, then specify one or more ranges in the *Percentiles* fields. Click the *X* to remove a percentile field. Click *+ Add* to add a percentile field. and relocate it at point of use.

wylieconlon · 2019-11-12T18:35:58Z

docs/user/visualize.asciidoc

-<<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. Hidden by default.


Need to update Timelion. It's shown by default.

wylieconlon · 2019-11-14T19:00:10Z

@KOTungseth @gchaps Any concerns with merging this? I think I've addressed your feedback so far.

gchaps

Discover LGTM.

) * [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

…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

…51360) * [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

[Docs] Update and improve docs for Visualize and Discover

e3e8fbc

wylieconlon added Team:Docs Team:Visualizations Visualization editors, elastic-charts and infrastructure release_note:skip Skip the PR/issue when compiling release notes v7.5.0 labels Oct 30, 2019

wylieconlon requested review from gchaps and KOTungseth October 30, 2019 22:35

Create a new section for default editor docs

1ae9ef3

wylieconlon marked this pull request as ready for review October 31, 2019 18:07

Fix significant terms link

610253e

gchaps reviewed Oct 31, 2019

View reviewed changes

docs/discover/field-filter.asciidoc Outdated Show resolved Hide resolved

docs/discover/field-filter.asciidoc Outdated Show resolved Hide resolved

Writer changes

de3763f

KOTungseth reviewed Oct 31, 2019

View reviewed changes

wylieconlon added 2 commits November 11, 2019 14:31

Merge remote-tracking branch 'origin/master' into docs-kibana-app

c86e3cd

Remove pages that aren't helpful to users

e4f0984

wylieconlon requested review from KOTungseth and gchaps November 11, 2019 21:03

wylieconlon commented Nov 12, 2019

View reviewed changes

More writer changes

de8bfc3

gchaps approved these changes Nov 14, 2019

View reviewed changes

KOTungseth approved these changes Nov 20, 2019

View reviewed changes

Merge remote-tracking branch 'origin/master' into docs-kibana-app

a4db4dc

KOTungseth merged commit 5f2a326 into elastic:master Nov 21, 2019

KOTungseth mentioned this pull request Nov 21, 2019

[7.x] [Docs] Update and improve docs for Visualize and Discover (#49810) #51359

Merged

KOTungseth mentioned this pull request Nov 21, 2019

[7.5] [Docs] Update and improve docs for Visualize and Discover (#49810) #51360

Merged

wylieconlon deleted the docs-kibana-app branch December 9, 2019 18:34

wylieconlon mentioned this pull request Jul 8, 2020

[Discuss][Docs] What to do with the supported aggregation page? #71054

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

wylieconlon commented Oct 30, 2019 •

edited

Loading

elasticmachine commented Oct 30, 2019

elasticmachine commented Oct 30, 2019

elasticmachine commented Oct 30, 2019

elasticmachine commented Oct 31, 2019

elasticmachine commented Oct 31, 2019

gchaps left a comment

KOTungseth left a comment

KOTungseth Oct 31, 2019

wylieconlon Oct 31, 2019

KOTungseth Oct 31, 2019

KOTungseth Oct 31, 2019

KOTungseth Oct 31, 2019

wylieconlon Oct 31, 2019

KOTungseth Nov 12, 2019

wylieconlon Nov 12, 2019

KOTungseth Oct 31, 2019

wylieconlon Nov 12, 2019

wylieconlon commented Nov 14, 2019

gchaps left a comment

		@@ -0,0 +1,101 @@
		[[supported-aggregations]]
		=== Supported aggregations

		All of these visualizations support:

		Metric Aggregations:

		Max Bucket:: The {ref}/search-aggregations-pipeline-avg-bucket-aggregation.html[_max bucket_]calculates the maximum value of a specified metric in a sibling aggregation

		Bucket Aggregations:

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

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

Conversation

wylieconlon commented Oct 30, 2019 • edited Loading

elasticmachine commented Oct 30, 2019

elasticmachine commented Oct 30, 2019

elasticmachine commented Oct 30, 2019

💚 Build Succeeded

elasticmachine commented Oct 31, 2019

💚 Build Succeeded

elasticmachine commented Oct 31, 2019

💚 Build Succeeded

gchaps left a comment

Choose a reason for hiding this comment

KOTungseth left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wylieconlon commented Nov 14, 2019

gchaps left a comment

Choose a reason for hiding this comment

wylieconlon commented Oct 30, 2019 •

edited

Loading