Quick start should be tutorial style documentation

I was thinking explain style, but structured kinda around visual variables:

I go back and forth on aesthetic first or mark type first, but I think having a consistent ordering/structure would make it a lot easier to build associations between "this artist class (and therefore these plot types) supports these visual stylings/parameters"

I was thinking explain style,

Maybe that's the fundamental question we should clarify first.

I see "Quick start" as the entry point for new users (similar to 10 minutes to pandas). The goal is that users can get productive and do their first plots relatively quickly. Do we agree so far?

Coming from https://docs.divio.com/documentation-system/

• tutorials - learning oriented
• explanation - understanding oriented

IMHO the focus should be on learning. Of course, they have to understand some concepts, but only as far as is needed to get a plot done. From https://docs.divio.com/documentation-system/explanation/:

Explanation, or discussions, clarify and illuminate a particular topic. They broaden the documentation’s coverage of a topic.

And that's not the goal of a quick start.

The quick start is definitely a tutorial. However even tutorials need to occasionally have some explanation if it is something that trips up many users at the beginning.

I think what happened here was the initial explanation of the difference between the interfaces was in the Quick Start, and then it got expanded because it was not explained anywhere else. Now that we have a more complete Users Guide, making this section of the Quick Start more concise with links for further explanation deeper into the UG makes good sense.

I see "Quick start" as the entry point for new users (similar to 10 minutes to pandas). The goal is that users can get productive and do their first plots relatively quickly. Do we agree so far?

Yes, I agree that quick start should be a broad overview of what folks can do/how to do the basic things.

On breaking down the structure of the Pandas overview, I'm revising my take on it being a tutorial but the thing I think is most important is that it's an end to end overview of the library - it gives very brief and sometimes incomplete code snippets b/c it's more focused on showing what and specific thing is and how to do just the thing.

And the only reason I'm stressing this is that my major issue w/ the current quick start guide is the structure. I think cleaning up the examples should fall out of the restructuring b/c like w/ the interface examples, they mostly grew unwieldy b/c of scope creep.

What I mean is take the pandas structure - it's "make data frame, view data data, subset, compute, merge/group/join/pivot, units, plotting, save out" That's a standard intro work process for a table and like concepts are grouped together.

Ours doesn't have as strong a narrative thread, (like coding style should probably be first if it's the info you need to know to understand why all the code is written the way it is...) and if you don't understand Matplotlib, it's unclear why ticks isn't under labeling data and if you don't know Matplotlib then styling artists doesn't mean anything and if you know a little it's not obvious why colormapping gets it's own thing (and also should be updated w/ the new colormapper).

That's why I'm proposing restructure where either the reader walks the work path one plot type family at a time (mark/artist first) or top level visual variable/styling/labeling where the reader walks the work path and sees an example for each plotting type in a consistent order.

And to be clear, none of this is meant as a critique of the efforts that went into writing it - getting it down in the first place makes it much easier to suggest an improved structure b/c there's something to work w/.