Mentioning Parameters in the docs

[maximlt]

Across the HoloViz documentation, be it in Panel, HoloViews or even hvPlot, there are often mentions of parameters which we understand as being Param Parameters (e.g. widget.param.value). parameter is such a general word that this practice is confusing in itself, even more so when users aren't aware of Param, which is very likely for hvPlot for instance.

I believe there should be a way for readers to clearly identify these are not normal parameters, e.g. parameters they find in a function signature, but Param Parameters. And the thing that allows to identify them as such should be used everywhere it's required, and in a similar way across the whole documentation. Options include for instance:

• linking to a relevant page (on Param's site I guess)
• applying some styling (e.g. *Parameter* instead of parameter)
• using tooltips to give more details
• or a combination of these options, e.g. linking + styling

[jbednar]

True. It would be great to have them link to their definition on the Parameterized object, but that seems like a lot of work.

[maximlt]

I'm not sure I understand what you mean. What I was referring to were cases such as "with pn.bind you can bind a function to widgets or parameters".

[jbednar]

Oh, you mean the word "parameter", not a specific parameter like max_levels. In that case, I think it should at a minimum be capitalized, and ideally should link to an appropriate location on the param web site. In general it would be great if anything we mention like that (with a capital) is automatically linked, and unless I'm dreaming I think we had some such support in nbsite or associated scripts, but I don't know if that actually worked or if it can be made to work across repos like that.

[maximlt]

Yes it is exactly what I meant - the word "parameter" - sorry I wasn't clear enough in the original post. Linking to the Parameters guide of Param would be an option, except that it is a tad long and what would work best in sort of case would be a glossary-like definition, short and to the point. Another option would be to link to the API reference of Parameter, if it was adapted to a more beginner-friendly audience. The advantage of that second option would be that we could leverage the cross-linking capabilities of the Sphinx ecosystem.

So I'd say that the steps to fix the issue include:

1. Define where to host that shared definition of Param Parameters
2. Write it in a way that users with no prior knowledge of Param (e.g. hvPlot users) can understand it
3. Reference this resource from the other websites (starting from Panel, then hvPlot, HoloViews, etc.)

[droumis]

I vote for linking to a relevant page on the param site. I think making them links also suffices as a styling modification.

Draft text for a plain language glossary-like definition: "Parameter is a special class attribute that allows for explicitly declaring behavior such as type, range, doc string, and default value."

[jbednar]

Sounds good to me! Slight modification: "A Parameter is a special class attribute that allows for explicitly declaring behavior such as type, range, doc string, and default value; see param.holoviz.org for details."

[maximlt]

Just noting that when Parameters are used in the context of hvPlot/HoloViews, what is also important is that Parameters can be watched. I.e. users would define a Parameterized P class with some attribute option, instantiate it as p and pass p.option.param to hvPlot/HoloViews, as in this example from HoloViews docs smoothed = rolling(stock_dmap, rolling_window=explorer.param.rolling_window).