Documentation plan

A major part of improving our docs is to add various examples. The way many libraries structure their examples is in a top-level examples directory (see bokeh, and matplotlib). These examples then usually get built into a gallery (see bokeh, matplotlib, and cartopy).

Adding an examples directory also encourages adding examples when new features are added. I’d even suggest that in future new features should be accompanied by small example notebooks or scripts. We are going to be splitting out the different plotting backends but I’d still strongly argue examples for officially supported backends should live on the core repo, where they are all in one place.

We’ve also had various definitions of examples in the past, what I think it should mean in this context is small self-contained notebooks with at most one or two examples, which are focused on the code, not on telling a story or explaining deeper concepts. That contrasts with quickstart guides, tutorials and the “examples” that are linked to from holoviews.org/Examples, which are really case studies. My suggestion for the different types of notebooks:

1. Tutorials - Long, detailed notebooks explaining particular concepts in detail, living in doc/Tutorials. New tutorials should be added to holoviews-contrib and can move to the main repo once polished.
2. Quickstart guides - Shorter notebooks getting the user started on using a particular feature without providing extensive background. Again should start out in holoviews-contrib but once we have a few I’d suggest creating a User Guide (see bokeh) that provides a quick introduction to holoviews.
3. Examples - These are what this issue is about, they are short and self-contained and generally should just go straight into the main repo since they don’t need detailed explanation.
4. Case studies - These are what’s currently on holoviews.org/Examples, and basically show how to apply holoviews to a particular domain or problem. I believe these should all live in holoviews-contrib providing a wide-ranging collection of user examples. Keeping them all in one place this way will encourage us to test and update them for each release.

If we agree on these different formats and where they live we should settle the structure of the examples, my suggestion is that each example should be implemented for all backends that support the features used in the example. Then each example links to the equivalent versions for other backends. Each example should contain the following information:

• Table with links to the example implemented using other backends using unicode tickmarks to show supported and unsupported backends
• List of requirements, e.g. if the data uses bokeh sample data lists that as a requirement
• A link to the original source of the example if any
• (Optional) A list of tags to make the examples more searchable

We also want to structure the examples into sensible subfolders. Here’s some subfolders I can currently imagine:

• apps - bokeh apps and in future maybe matplotlib webagg based apps
• elements - All the supported elements split out into individual notebooks
• plotting - Basic examples showing off specific plotting features
• streams - Various examples using regular streams and linked streams

[jbednar]

We can’t be everywhere! 😃 We’ll be talking about HoloViews, Datashader, and Bokeh at SciPy in Austin, JupyterCon in NYC, and FOSS4G in Boston, two of which are in-depth tutorials.

Yes, we’re working on better overview/howto guides. We’ll soon be making a new site that covers multiple projects (HoloViews, Bokeh, and Datashader at least) that shows how everything fits together to solve real problems. Stay tuned!

[jlstevens]

It has been a ton of work but now this plan has been implemented. Very happy to close this one!