[Vega] Write tutorials and reference #71028

wylieconlon · 2020-07-08T00:16:13Z

Preview
Diff

Closes #70478
Closes #70267

elasticmachine · 2020-07-08T00:16:15Z

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

nyurik

Thank you so much for adding all the wonderful docs for Vega! I added a few comments and suggestions inline.

nyurik · 2020-07-08T04:16:38Z

docs/visualize/vega.asciidoc

@@ -3,71 +3,2114 @@

 experimental[]

-Build custom visualizations from multiple data sources using Vega
-and Vega-Lite.
+Build custom visualizations using Vega and Vega-Lite, backed by any


Suggested change

Build custom visualizations using Vega and Vega-Lite, backed by any

Build custom visualizations using Vega and Vega-Lite, backed by one or more

nyurik · 2020-07-08T04:18:34Z

docs/visualize/vega.asciidoc

+that {kib} provides, but with higher complexity. The most common reason
+to use Vega in {kib} is that your data or
+visualization isn't supported in other tools in {kib}, so you need
+to use the more powerful tool. The most common reasons to use Vega in {kib} are:


duplicate "the most common reason" here and a few lines above.

nyurik · 2020-07-08T04:21:49Z

docs/visualize/vega.asciidoc

+
+and click "Update". The result is probably not what you expect, because it shows
+a flat line with 0 results. This shows the first thing that you need to understand
+when writing a Vega spec in {kib}: small changes can lead to unexpected results.


LOL :) As a first lesson, I think we should rather add something like "baby steps - make sure to frequently refresh (i.e. Ctrl+Enter or auto-apply) - to see the result of each minor change". But I'm not too sure of how to phrase it, so maybe its ok to leave as is.

nyurik · 2020-07-08T04:22:24Z

docs/visualize/vega.asciidoc

+
+* Use intuition to guess at the problem
+* Open the browser dev tools and look at the Network tab to inspect the {es} request
+* Open the browser dev tools and type `VEGA_DEBUG.vegalite_spec.data` to inspect


Suggested change

* Open the browser dev tools and type `VEGA_DEBUG.vegalite_spec.data` to inspect

* Open the browser dev tools console and type `VEGA_DEBUG.vegalite_spec.data` to inspect

nyurik · 2020-07-08T04:23:07Z

docs/visualize/vega.asciidoc

+* Open the browser dev tools and type `VEGA_DEBUG.vegalite_spec.data` to inspect
+    the response from {es}
+* Build a comparable query using the {kib} Dev Tools and see if the results match
+* Copy the spec from `JSON.stringify(VEGA_DEBUG.vegalite_spec)` and paste into the


This should probably link to the vega editor?

nyurik · 2020-07-08T04:24:07Z

docs/visualize/vega.asciidoc

+* Use `VEGA_DEBUG.view.data('source_0')` or `VEGA_DEBUG.view.data('data_0')` to
+    understand the transformations that are applied after fetching data
+
+This complex debugging process will come up frequently while working on Vega in {kib}.


I don't think we should write "this complex debugging process" - no reason to scare people ahead of time ;)

nyurik · 2020-07-08T04:24:55Z

docs/visualize/vega.asciidoc

+Now, let's make the visualization more interesting by adding another aggregation
+to create a stacked area chart.
+
+Click the wrench icon and select "Reformat as JSON, strip comments". Now, open


why reformat?

docs/visualize/vega.asciidoc

wylieconlon · 2020-07-14T21:42:18Z

@nyurik Can you take another look? I updated the intro and rewrote the Vega tutorial, which I think addresses your feedback.

timroes

This looks really good overall. I've left a couple of suggestions. Most of them are optional.

Two additional notes. In line 1384 of the vega.asciidoc we're missing an opening backtick around "%timefield%", maybe we can also add it in this PR.

I wonder - since I assume a lot of people will come through the tutorial before jumping to the reference - if it's worth adding a note about %context% and %timefield% already into the tutorial when we first use it in the spec.

timroes · 2020-07-15T11:46:05Z

src/plugins/vis_type_vega/public/vega_view/vega_base_view.js

@@ -147,7 +147,7 @@ export class VegaBaseView {
            defaultMessage:
              'External URLs are not enabled. Add   {enableExternalUrls}   to {kibanaConfigFileName}',
            values: {
-              enableExternalUrls: 'vega.enableExternalUrls: true',
+              enableExternalUrls: 'vis_type_vega.enableExternalUrls: true',


🕵️‍♂️ good catch

timroes · 2020-07-15T11:49:35Z

docs/visualize/vega.asciidoc

-* *Vega* &mdash; A declarative format to create visualizations using JSON.
-  Generate interactive displays using D3.
+Vega and Vega-Lite are both declarative formats to create visualizations
+using JSON. Vega-Lite is an easier format to use that compiles into Vega.


Suggestion: "Vega-Lite is an easier but less powerful format to use [that compiles into Vega]."

Should we mention "compiles into Vega" in a user-facing documentation? Wording wise as, is this information relevant for users? (I am open for both, just lose thoughts.)

I've clarified this

timroes · 2020-07-15T11:51:10Z

docs/visualize/vega.asciidoc

+Vega and Vega-Lite are capable of building most of the visualizations
+that {kib} provides, but with higher complexity. The most common reason
+to use Vega in {kib} is that your data or
+visualization isn't supported in other tools in {kib}, especially


Suggestion: Could we replace the "especially in these cases", by something a bit more lose like "for example the following cases". I feel (but threat this with the grain of salt of a non-native speaker), that in the current phrasing we kind of advertise using Vega in all those cases, while e.g. bucket script users could potentially find "better" solutions in other visualization tools inside Kibana.

timroes · 2020-07-15T11:52:11Z

docs/visualize/vega.asciidoc

+* Custom maps
+* Using a visual theme that {kib} does not provide
+
+Because Vega supports all of these, it is often easier to write a Vega spec


Suggestion: Since we still officially don't recommend writing custom plugins (and e.g. don't allow them running into our cloud), I am not sure if we should make this comparison here at all.

timroes · 2020-07-15T11:54:29Z

docs/visualize/vega.asciidoc


-Go to `mark`, change the value to a different visualization type, then click
-*Update*.
+The first step is to change the index to one of the <<add-sample-data, sample data>>


Suggestion: I mean kind of obvious, but wonder if we should still mention, that they should make sure the ecommerce sample data set is installed?

timroes · 2020-07-15T11:59:14Z

docs/visualize/vega.asciidoc

+Open the browser dev tools console and type
+`VEGA_DEBUG.view.data('data_0')`. You will see:


I wonder if we should change the phrasing here, to not look like too similar to the previous paragraph. I first thought it's a duplicate. So many we could write something like: "Now type VEGA_DEBUG.view.data('data_0') into the console to see the data used by the chart."

timroes · 2020-07-15T12:06:32Z

docs/visualize/vega.asciidoc

+        }
+      }
+    }
+  }]


This snippet does not contain the opening [, so we should remove the ] here.

timroes · 2020-07-15T12:09:11Z

docs/visualize/vega.asciidoc

-the `"url"` value.
+{kib} registers a default https://vega.github.io/vega/docs/schemes/[Vega color scheme]
+with the id `elastic`, and sets a default color for each `mark` type.
+Override it by providing an alternate


The end of this sentence is somehow missing.

timroes · 2020-07-15T12:11:21Z

docs/visualize/vega.asciidoc

+* `{%timefilter%: true}`: Replaced by an {es} range query with upper and lower bounds
+* `{%timefilter%: "min" | "max"}`: Replaced only by the upper or lower bounds
+* `{%timefilter: true, shift: -1, unit: 'hour'}`: Generates a time range query one hour in the past
+* `{%autointerval%: true}`: Replaced by the string representing the time interval, such as `1h`


Suggestion: Let's clarify a bit more what "the time interval" means here, e.g. something like "Replaced by a string representing a reasonable sized interval, for most charts over time" (I don't like my version of this sentence, but something along those lines, maybe).

timroes · 2020-07-15T12:15:56Z

docs/visualize/vega.asciidoc

+* https://vega.github.io/vega/docs/[Docs]
+* https://vega.github.io/vega/examples/[Examples]
+
+TIP: When you use the examples, you may


Suggestion: "When you use the examples in Kibana, you may ..."

wylieconlon · 2020-07-15T18:02:10Z

@alexwizp I am not documenting the new Vega inspector here because I'm trying to merge these docs for 7.9. Do you think we need a followup issue for 7.10 docs?

kibanamachine · 2020-07-15T18:16:56Z

💚 Build Succeeded

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

Build metrics

async chunks size

id	value	diff	baseline
visTypeVega	2.1MB	+17.0B	2.1MB

miscellaneous assets size

id	value	diff	baseline
upgradeAssistant	22.5KB	-28.0B	22.6KB

History

💚 Build #61690 succeeded b2e810d
💚 Build #59618 succeeded a24a0a3

To update your PR or re-run it, just comment with:
@elasticmachine merge upstream

KOTungseth

LGTM!

* [Vega] Improve all Vega docs * Rewrite Vega tutorial to introduce from empty visualization * Update from feedback

* [Vega] Write tutorials and reference (#71028) * [Vega] Improve all Vega docs * Rewrite Vega tutorial to introduce from empty visualization * Update from feedback * Fix image path by moving to new folder Co-authored-by: Elastic Machine <[email protected]>

[Vega] Improve all Vega docs

a24a0a3

wylieconlon added Team:Docs Feature:Vega Vega visualizations v8.0.0 release_note:skip Skip the PR/issue when compiling release notes v7.9.0 labels Jul 8, 2020

wylieconlon requested review from nyurik, alexwizp, KOTungseth and a team July 8, 2020 00:16

nyurik reviewed Jul 8, 2020

View reviewed changes

timroes mentioned this pull request Jul 14, 2020

Bringing Vega out of experimental #21721

Closed

20 tasks

wylieconlon added 2 commits July 14, 2020 14:29

Merge remote-tracking branch 'origin/master' into vega-docs

8b34df1

Rewrite Vega tutorial to introduce from empty visualization

b2e810d

timroes approved these changes Jul 15, 2020

View reviewed changes

wylieconlon added 2 commits July 15, 2020 11:44

Update from feedback

76ce625

Merge remote-tracking branch 'origin/master' into vega-docs

f17c19d

wylieconlon requested a review from nyurik July 15, 2020 18:01

KOTungseth approved these changes Jul 15, 2020

View reviewed changes

wylieconlon merged commit 97d8128 into elastic:master Jul 15, 2020

wylieconlon deleted the vega-docs branch July 15, 2020 18:51

wylieconlon mentioned this pull request Jul 15, 2020

[7.x] [Vega] Write tutorials and reference (#71028) #71928

Merged

wylieconlon pushed a commit to wylieconlon/kibana that referenced this pull request Jul 15, 2020

[Vega] Write tutorials and reference (elastic#71028)

8a1f969

* [Vega] Improve all Vega docs * Rewrite Vega tutorial to introduce from empty visualization * Update from feedback

wylieconlon mentioned this pull request Jul 15, 2020

[7.9] [Vega] Write tutorials and reference (#71028) #71929

Merged

wylieconlon pushed a commit to wylieconlon/kibana that referenced this pull request Jul 15, 2020

[Vega] Write tutorials and reference (elastic#71028)

ab7f87c

* [Vega] Improve all Vega docs * Rewrite Vega tutorial to introduce from empty visualization * Update from feedback

wylieconlon pushed a commit that referenced this pull request Jul 15, 2020

[Vega] Write tutorials and reference (#71028) (#71929)

b1e7bc7

* [Vega] Improve all Vega docs * Rewrite Vega tutorial to introduce from empty visualization * Update from feedback

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[Vega] Write tutorials and reference #71028

[Vega] Write tutorials and reference #71028

wylieconlon commented Jul 8, 2020 •

edited

Loading

elasticmachine commented Jul 8, 2020

nyurik left a comment

nyurik Jul 8, 2020

nyurik Jul 8, 2020

nyurik Jul 8, 2020

nyurik Jul 8, 2020

nyurik Jul 8, 2020

nyurik Jul 8, 2020

nyurik Jul 8, 2020

wylieconlon commented Jul 14, 2020

timroes left a comment

timroes Jul 15, 2020

timroes Jul 15, 2020

wylieconlon Jul 15, 2020

timroes Jul 15, 2020

wylieconlon Jul 15, 2020

timroes Jul 15, 2020

wylieconlon Jul 15, 2020

timroes Jul 15, 2020

wylieconlon Jul 15, 2020

timroes Jul 15, 2020

wylieconlon Jul 15, 2020

timroes Jul 15, 2020

wylieconlon Jul 15, 2020

timroes Jul 15, 2020

wylieconlon Jul 15, 2020

timroes Jul 15, 2020

wylieconlon Jul 15, 2020

timroes Jul 15, 2020

wylieconlon Jul 15, 2020

wylieconlon commented Jul 15, 2020

kibanamachine commented Jul 15, 2020

KOTungseth left a comment

	Build custom visualizations using Vega and Vega-Lite, backed by any
	Build custom visualizations using Vega and Vega-Lite, backed by one or more

	* Open the browser dev tools and type `VEGA_DEBUG.vegalite_spec.data` to inspect
	* Open the browser dev tools console and type `VEGA_DEBUG.vegalite_spec.data` to inspect

		Open the browser dev tools console and type
		`VEGA_DEBUG.view.data('data_0')`. You will see:

[Vega] Write tutorials and reference #71028

[Vega] Write tutorials and reference #71028

Conversation

wylieconlon commented Jul 8, 2020 • edited Loading

elasticmachine commented Jul 8, 2020

nyurik 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

wylieconlon commented Jul 14, 2020

timroes 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

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 Jul 15, 2020

kibanamachine commented Jul 15, 2020

💚 Build Succeeded

Build metrics

async chunks size

miscellaneous assets size

History

KOTungseth left a comment

Choose a reason for hiding this comment

wylieconlon commented Jul 8, 2020 •

edited

Loading