suggestion for future tutorial/examples

[dhruvbalwada]

I am a new user to holoviz and started by going through the tutorial (https://holoviz.org/tutorial/index.html) and listening to a recording https://www.youtube.com/watch?v=7deGS4IPAQ0
I think all these tools are really cool and very useful!!

I am trying to build a simple dashboard that connects a few and different data sources, which share a time axis. I want to put them all together so I can easily collocate features and notice and patterns and connections between the data. I have managed to get quite far, but it has been a real pain!

The biggest issue I have faced is that the tutorials, user guides, and gallery examples across the different projects are almost never consistent with each other. Everytime I want to do something this is what happens:
a) I find it in the tutorial, realize that what I want to do is slightly more complicated so I look for a gallery item.
b) When I find the gallery item and start reading the code, I realize that it is algorithmically different from the tutorial (maybe doesn't use panels or does something else in a very different way than the tutorial). This usually means some different functionality is being used from one of the other libraries.
c) So then I end up on the website of that library, only to find that now I have to go through a new user guide. This user guide ends up not being consistent with the gallery example or the tutorial, and leads me to to the user guide of another library.
d) So, all this makes me run around in circles - if I want to do anything that is a little more advanced than the standard options that are available, which is almost always the case when making dashboards.
e) I even tried looking at the examples of dashboards that are fully self contained (example Glaciers), but they seem to also be operating differently from the tutorial to some degree.

I am probably just very confused, it has only been 1.5 weeks since I started getting into this. I also understand that different tools are being developed simultaneously, so all the different user guides are not going to be up to date with each other. But, maybe in the future developments some attention can be paid to consistency across libraries.

One way to do this might be that holoviz decides on some standard operating procedure and then tries to always stick to it in all the basic examples and tutorials. Obviously, this will not always work, and things might have to be done differently in some cases. When this need arises it should be clearly documented why things were done differently, and when should a user go down that advanced path. Right now there is too much variation between basic examples.

Maybe this is already on your future agenda, and hopefully this does not come across as rude. I just thought it best I shared my experience as a new user, because probably in a few months when I have learned enough about the ecosystem I will know the nuances and not even remember that I was having this issue. It definitely can be a barrier to entry since it creates a very steep learning curve.

[jbednar]

I feel your pain! The tools in the HoloViz ecosystem are updating rapidly, which means that an example written in the best available way in month X-6 would probably be written a different way in month X. The old way generally still works, but it's not necessarily how we'd go about things now.

Glaciers is a good example -- that was one of the first full-featured Panel dashboards we made, and since then some amazing new link_selections functionality has been added to HoloViews that greatly simplifies how an app like Glaciers can be built. Some of that functionality was directly inspired by Glaciers, with features needed there driving improvements to the underlying libraries. I believe @philippjfr actually now has a new version of Glaciers ready that is vastly simpler, using link_selections, but I'm not sure if he's published that yet. Hopefully soon, if not!

The underlying issue is that it takes time and experience to realize the best, most natural interface for some functionality, and once we do, we try to make sure our most prominent examples use that. But it's then time-consuming to go back and update previous examples, and we can't get that all done at once.

This is definitely an area where we'd love user contributions, taking our "best practice" suggestions (anything in the most recent full tutorial on a topic) and applying it to the scattered gallery examples to bring them up to date. I'd love if an interested user or group of users could note which examples seem to be using outdated approaches, list them in an issue here or in the relevant library, get agreement that it makes sense to make those consistent with current approaches, and then update the examples.

[dhruvbalwada]

Thanks, yes would be great if users can slowly update the examples and note which ones need to be. I will try to when I can, and hope other new users do too. Maybe a note can be left on the tutorial/examples pages about this.

One thing that might help is if the examples and tutorials have "last updated" date in them. This way when faced with an example that looks very different from some tutorial a new user can assume that some of the style might be older, and not necessarily a lack in their understanding. This is one of the struggles I have had, to parse between what is a stylistic difference vs essential algorithmic difference.

[jbednar]

I'm afraid that's one of the many, many undone tasks on our to-do list. :-/

• Specifically, everything on examples.pyviz.org should have an author and a date prominently listed, because each one of those covers specific topics from one person's (or sometimes two people's) perspective; they are each a snapshot in time. We don't promise to update those as new versions of libraries are released. I'm probably the only one who knows who did all the work on all of those, so it's really up to me.
• I think the same should go for http://holoviews.org/gallery ; each of those should have a date on them, and many of them are ancient translations of Bokeh examples, not at all how we'd go about doing those things nowadays. @jlstevens or @philippjfr would be the ones to know where those came from.
• https://panel.holoviz.org/gallery is less out of date, but there are better ways to do at least some of those now. They probably also do need authors, both to credit them and to make it more clear that they are also snapshots that won't necessarily be updated with each new release. @philippjfr would be the one to know about those.
• The content at holoviz.org is generally updated all at once, without authors for each page, so that could have a date the tutorial was last presented.
• The rest of our websites are generally docs, not examples, and docs are always meant to be kept up to date (even if some like HoloViews have dusty corners that we haven't noticed).