Composition Docs Revision

[kanitw]

• [ ] Rule Mark
  • [ ] ruleSize, ruleRangeSize

[kanitw]

composition.md

• [x] layer is a bit too detailed

Vega-Lite automatically unions scale domains and combines axes and legends. However, Vega-Lite can not enforce that a unioned domain is semantically meaningful. To prohibit layering of composite views with incompatible layouts, the layer operator restricts its operands to be single or layered views.

I think these information are too detailed for a composition intro page.

[mcorrell]

• [x] The resolve page is a little too abstract, compared to the others. It could benefit from an example, and some words about when these field should be used (like with the other docs, esp. mark and composition).

[kanitw]

facet.md

• [x] Missing details in the properties table
• [x] Missing links for special properties in the properties table
• [x] Add example to help explain how a shortcut is transformed (normalized) into a full spec
• [x] Missing sort
• [x] Missing details about how to customize facet labels and title -- @kanitw

A FacetFieldDef is similar to a channel definition.

• [ ] once we refactor encoding.md to distinguish field def and value def, we should say field def here, not channel def.

[light-and-salt]

Through this hierarchical composition, you can create a whole dashboard as a single specification.

This is so exciting! It would be nice if there is an example specification for a whole dashboard.

The word "dashboard" makes me think of layout, which Tableau and PowerBI supports. Those kind of dashboards typically have views organized in various ways (e.g., small and large views on the same page, repeated views, concatenated views and layered views on the same dashboard etc.). I can kind of foresee how it can be achieved by "hierarchical composition". Just wondering if that's the kind of dashboard you mean here...

[jhoffswell]

On the resolve page, you say:

The defaults documented on the faceting, layering, concatenation, and repeating pages.

However, the documentation for resolve on these pages seems to generally be about one sentence, e.g.

The default resolutions for facet are shared scales, axes, and legends.

If the default documentation is going to be this short on the other pages, I think it might be more reasonable to just include the same level of documentation on this page as well, rather than requiring the user to check each other page individually. Maybe something like:

The default resolutions for facet and layer are shared scales, axes, and legends. The default resolutions for concatenation are independent scales, axes, and legends. The default resolutions for repeat are independent scales and axes for spatial channels and shared scales and legends for legends.

[jhoffswell]

On the repeat page, you say:

To create a faceted view, define how the data should be faceted in facet and how each facet should be displayed in the spec.

This sentence probably needs to be changed (or removed) for this page.

[jhoffswell]

On the composition page, it might be nice to have small examples/images to help explain what each operator is for to help readers find the correct part of the documentation for their task.

[jhoffswell]

On the layer page, you say:

This operator is none of Vega-Lite’s view compositon operators.

Which has two typos, fixed below:

This operator is one of Vega-Lite’s view composition operators.

[jhoffswell]

On the layer page, when you say:

The population of the German city of Falkensee over time. Based on a visualization built using Vega.

The link does not work.

[kanitw]

• [x] Clarify that https://github.com/vega/vega-lite/issues/2415 is not supported yet

[domoritz]

Fixed broken link to fsee example in c04f86d0. Thanks @jhoffswell!

[domoritz]

Fixed typos in 87340ccf

[kanitw]

• [x] Examples for concat docs (https://github.com/vega/vega-lite/issues/2886)

[kanitw]

• [x] Add more examples to the gallery

[kanitw]

• [x] How to modify axis properties (e.g., title) for shared scale