Improve documentation by separating dataset creation

While trying to learn Holoviews and Datashader, in order to create figures with numerous plots containing numerous time-history Curve elements, I’ve found it difficult to digest many of the examples in the documentation. I think this is because the examples, in the Large Data - Multidimensional Plots section for example, combine very concise “creation of the source data” logic, within the very example that is trying to introduce new users to a function. The result is a pretty amazing example of doing many complex things in a small amount of code, but I feel that makes it difficult to decipher proper use of the method being described.

For example, in the section linked above, and in many sections on that page, the authors make extensive use of dictionary and list comprehensions in order to concisely construct the data sources feeding a function, and the method’s arguments are all formed through layers of iterations and iterables. However, I’m bringing in various sets of data from other files, and I think I need to define these arguments discretely, and so I find myself a little lost in how these comprehensions apply to my use case.

Make sense? Is there a more-productive place to submit this concern?

1 Like

Hey @CrashLandonB, thanks for the great feedback. That makes total sense. We are starting to take another look at all of our docs and we will definitely take this into account.

2 Likes

Hi @CrashLandonB

A place to direct the discussion with more concrete impact would be a GitHub issue with an associated PR to improve one of the examples.

The review process of the PR would potentially lead to a better knowledge of how to write great documentation and the improved example could be an inspiration for other doc improvements.

Thanks for taking your time to provide feedback and suggest improvements. Much appreciated.

1 Like