search

holoviz-topics / examples

Visualization-focused examples of using HoloViz for specific topics
https://examples.holoviz.org
Creative Commons Attribution 4.0 International
82 stars 24 forks source link

Naming conventions for projects #38

Closed jbednar closed 4 years ago

jbednar commented 5 years ago

By design, pyviz-topics/examples has a flat structure, because maintaining any hierarchical structure based on categories or other semantic groupings seems untenable over time. Many examples illustrate multiple libraries, multiple concepts, and so on, and as examples come and go, new hierarchical groupings and categories will emerge. We don't want the underlying URLs to ever have to change, and so we are using a single flat structure. Groupings can be provided by any site that links to these examples, and those groupings can change over time without breaking the URLs.

With that in mind, we need some sort of convention for how to name the projects. The same principle of needing to assign a static URL and not revisit that decision over time applies here; e.g. if some project is added and then another related one needs to be distinguished from it, then we shouldn't need to change the original URL to achieve that. E.g. if there is already an "attractors" project based on Datashader and a new one is added based on Vaex, we could rename the first one to "attractors_datashader" and the new one could be "attractors_vaex", but then links would break.

I think there are only two ways to avoid breaking links, only one of which is feasible. The infeasible way is to ensure that the name initially includes all the information that might vary in some subsequent project. E.g. the attractors project is based on Datashader and Panel, so it could be called attractors_datashader_panel, in anticipation of there someday being attractors_vaex_panel and attractors_datashader_dash and attractors_vaex_dash. I don't think that approach is feasible; there will always be some other thing that could vary between projects, and anticipating all of them seems doomed to failure. Plus, some examples already demonstrate lots of libraries (intake, dask, numba, datashader, bokeh, holoviews, hvplot, and panel, in at least one existing case), which would lead to a ridiculously long URL.

So I think the only feasible policy is:

  1. New examples should have a relatively short name (e.g. "Attractors"), accurately conveying the topic being covered.
  2. Related examples added later should add a relatively small amount of text to the original name, whatever is needed to distinguish it from the previous examples (e.g. "Attractors_dash").

Does anyone see any better approach than this?

jbednar commented 4 years ago

We've taken this approach in practice without any issues over the past six months, and no one has raised a better proposal, so we'll consider this proposal accepted. :-)