jbednar
commented
5 years ago That all sounds good.
I think it would be useful to have a gallery of side-by-side comparisons of hv/bokeh/mpl plots, but that's not what we have now, and should be something separate from the current categories of what we do show in the gallery.
The reason to separate the textual names from the graphical thumbnail is that Jean-Luc objected to having multiple thumbnails with the same label. I didn't think that was a problem at all, because to me the thumbnails form a graphical or visual index, where the goal is to have a wide array of example images that the user can quickly scan and browse in 2D, clicking on anything that looks like it might be what they are trying to make and then they can see how to do it. To me whether each Element results in one or multiple thumbnails is irrelevant to that task; the key is to have some image of each of the different types of things we have shown can be produced, with as many of them in front of user eyeballs as possible, so that the user can recognize one, regardless of whether those things come from the same or multiple Elements. Jean-Luc was arguing that the list, at least in the Reference Gallery, is primarily a list of the available Elements, with the thumbnails only being a helpful visual representation of that element.
So we agreed that the Reference Gallery was serving two separate goals, and thus propose to separate the solutions for those two goals explicitly: One textual, alphabetic, one-to-one list of Element types, followed by a separate graphical, one to many collection of thumbnails illustrating some fraction of the various "looks" that can be achieved with these elements. I'm happy with that, though I still don't particularly see the need for separating the two lists, as having the same name be repeated seems ok to me. But it doesn't seem ok to Jean-Luc to repeat them, so I'm fine with separating the textual and the graphical lists, and doing so should make it easier to find the elements by name.
Following a discussion with @jbednar, we came up with some ideas for improving the galleries.
For the reference gallery, we could break down the elements section into subcategories by semantic types (charts, raster, stats etc) and have headings for each. Then under each heading, you can have an alphabetical list of the corresponding classes (note, currently we aren't using alphabetical order!) and under that, a visual index.
A visual index would be a bit different from what we have now 1) no text below each thumbnail 2) multiple thumbnails pointing to a single element notebook (i.e multiple thumbnails per element notebook, related to https://github.com/pyviz/nbsite/issues/99). Then you can just click on whatever looks like what you want and if you want to immediately see the class name, it is still there from the hover info (unchanged from current behavior).
As for the example gallery, a lot of the notebooks there need explanatory text (at least enough to link to the corresponding element notebooks) and many of the examples that use only a single element could be folded into the element notebooks completely. Historically, this gallery has been designed to match bokeh/matplotlib examples but that isn't really made explicit anywhere.
Another issue with the current examples is that they explicitly use only a single display at the end. This is restrictive and you can also imagine multiple thumbnails for the notebooks in this gallery (these examples could be like mini-topics).
As for an explicit topic section (which we don't have yet), it should have thumbnails pointing to pyviz topics (e.g earthml, earthsim) as well as our own miscellaneous topic notebooks within holoviews.