Yeah, I can totally imagine why this would be a challenge.
Have you thought about trying to grab this documentation issue from the other way around and create enrich the API reference like pandas did? Their API documentation is by modules and by functions, but it contains a reproducible example for practically every possible parameters, so whenever I run into a new function or a previously unknown parameter, I don’t have to guess what they mean by the description, I can immediately see it in action. This itself, of course, would not help much in understanding the underlying logic behind the tools and to answer “which function do I use to…?” questions, but at least if I managed to find a function that supposedly does what I want, I won’t be stuck with just a docstring in the function definition itself that assumes a deeper understanding of the vocabulary than what I possess. And also, their “See also” blocks at least give me an opportunity to go through possibly relevant other functions until I find what I’m looking for.
This, of course, would also be an enormous undertaking, especially with everything changing as rapidly as they do, but maybe it would disable the “we don’t know what newbies don’t know” barrier and resolve the “more documentation makes it harder to find anything” issue as everything is explained right where its definition is. And then the current “let us show you how stuff works in practice” type of notebooks would only sit on top of this, not bearing the burden of having to explain every parameter. Also, this probably would be easier to start with and to include volunteers in, as an initial documentation most probably could be generated from the already existing docstrings and while that itself would not provide any additional benefits compared to the docstrings themselves, it would allow us to contribute with smaller examples in smaller areas we are pretty sure already understand instead of the current barrier where I would have to have a pretty wide and deep understanding to create a full-blown example notebook and to be sure in not just that it works, but that it is actually the best way to implement that solution. Listing all the opts available for hv.Points with an example for each would be a much more well-defined task with a lower chance to accidentally spread misinformation.
Not trying to be smarter than you guys, just thought to share my viewpoint as a possible inspiration, as somebody who’s really grateful for these tools but still somewhat on the other side of this barrier…