Ideas for improving the new documentation

[MarcSkovMadsen]

The upcoming revised documentation is a great improvement. I've already learned a lot and believe I understand Param and the ideas behind it much better. It's great.

The below is a list of ideas that I believe could improve the documentation for both new and experienced users.

1. Make it even more visible WHY Param would be valuable to "me".

The documentation is text heavy. I think that is great as soon as my attention has been caught and I understand why I should take the time to read and learn. The text is great.

I need something to catch my attention though. And explain it to people with other learning preferences than text.

My suggestion would be to add a 3 min video to the Introduction that explains the why with a real world, practical example. It should be a walk through of a very interactive Notebook that can be downloaded by the user right next to the video. And add in a link to Binder where I can try it out as well.

It might also be valuable to add a 30 sec .gif video that just plays and immediately explains the Why to me and catches my attention.

2. Make Getting Started Example even more friendly for users.

The first example I see looks like this.

import param
        
class A(param.Parameterized):
    title = param.String(default="sum", doc="Title for the result")
    
class B(A):
    a = param.Integer(2, bounds=(0,10), doc="First addend")
    b = param.Integer(3, bounds=(0,10), doc="Second addend")
    
    def __call__(self):
        return self.title + ": " + str(self.a + self.b)

>> o1 = B(b=4, title="Sum")
>> o1.a = 5
>> o1()
'Sum: 9'

The main question for me is whether using __call__ in the example is a good idea. I know about __call__ but I never see any colleagues or blogs in data, engineering, trading or science use it.

So I believe the big questions for users is: What is __call__. Why do you use __call__. I did not know I needed __call__ in my code. What is the use case for __call__? Why is __call__ useful to me?

So unless there is a point (which a have not yet understood) in using __call__ I would rename the function to sum.

You are also using multiple inheritance which might also throw some users off. I just see my new colleagues coming out of engineering and finance education struggling with the concept of Classes.

3. Add Pydantic to the Comparison

Pydantic is taking the Python world with storm. Together with FastApi. I would like to know why it's valuable to me to build domain models with Param when

1. I can use Pydantic and not Param with FastAPI.
2. Pydantic works using type annotations which provides a much better development experience in an IDE and with linters than Param.
3. The huge popularity of Pydantic means more colleagues would probably know and understand why I use Pydantic
4. There are (more) tools out there for Pydantic like PyCharm, MyPy, Hypothesis plugins. And more are probably coming.
5. Lots of orgs are building on Pydantic and want to be associated with it. See https://github.com/Kludex/awesome-pydantic

I believe Param and Pydantic could be integrated and that would help a lot of Pydantic users easily create visualizations, tools, apps and dashboards from their models. And Param users create modern Rest Apis via Fast Api. For a Streamlit+Fast API example check out https://testdriven.io/blog/fastapi-streamlit/.

4. Add a real world example

Add a section with a real world example. My personal profile would simply need that. You can write just as many theoretical arguments about why Param is great (which it is) but without a real, practical example you don't catch my attention. I move on.

I work with traders so in my world the Black Scholes option pricing model is a great example.

I would visualize it using Panel.

There are probably more generally understandable examples out there but this one I use at work to explain why Param is powerful.

FYI. @jbednar

[jbednar]

1. Make it even more visible WHY Param would be valuable to "me".
   My suggestion would be to add a 3 min video to the Introduction that explains the why with a real world, practical example. It should be a walk through of a very interactive Notebook that can be downloaded by the user right next to the video. And add in a link to Binder where I can try it out as well.

Sounds like a great idea!

However, what do you mean by "interactive"? If you mean Panel, I think that may muddy the waters a bit; I think it's important for people to understand that Param is important in its own right, whether or not you ever make a GUI with Panel. So I think any first example should not use Panel.

2. Make Getting Started Example even more friendly for users.
   def __call__(self):
   The main question for me is whether using call in the example is a good idea. I know about call but I never see any colleagues or blogs in data, engineering, trading or science use it. So I believe the big questions for users is: What is call. Why do you use call. I did not know I needed call in my code. What is the use case for call? Why is call useful to me?

Hmm; good point; probably assuming people know too much about Python classes. Personally, I believe that if a Python class does only one thing, as this one does, it's simply good practice to name that thing __call__, instead of coming up with some other arbitrary method name for people to learn and keep track of. I.e., __call__ just means "do the thing this class does, whatever that is". If all other things are equal, I believe examples should demonstrate good practice by default, to maximize the exposure that people get to good patterns rather than bad patterns.

Still, it's also important not to derail people from their current objective by confusing them, particularly not in introductory examples; it's not our job to train people in Python language feature usage! So I'd be happy to accept a change to rename that to sum, to avoid putting off people without that background.

You are also using multiple inheritance which might also throw some users off.

This example is not using multiple inheritance. Each class inherits from only a single base class, i.e. B(A) (B inherits from A) where A(param.Parameterized) (A inherits from Parameterized).

But sure, you're asking whether it's important to show such an inheritance hierarchy here. I do think inheritance hierarchies like that are an extremely important aspect of Param, and I do want all Param users to be aware that Param is particularly well suited to such hierarchies, allowing you to avoid duplication along the inheritance chain (particularly for docstrings). Without Param, tall inheritance chains almost never bother to document individual parameters well, because that same bit of docs would have to be duplicated at every parent and child class in the chain, because Python inherits methods and attributes across the hierarchy, but not attribute docs. If we don't have such a chain in the examples, we can't show one of the main reasons to use Param, i.e. that it lets you organize your code well and without duplication. Without such inheritance, Python users have a disincentive to design proper inheritance hierarchies; Param fixes that!

That said, it doesn't necessarily need to be the first example! :-)

3. Add Pydantic to the Comparison. Pydantic is taking the Python world with storm. Together with FastApi. I would like to know why it's valuable to me to build domain models with Param when

Great idea; can you please contribute a section covering Pydantic to the Comparison? I don't use Pydantic myself, and from a relatively brief study of the docs I don't see what it would offer me that I don't already have with Param. It would be great to have a more useful perspective from someone who has used both!

I believe Param and Pydantic could be integrated and that would help a lot of Pydantic users easily create visualizations, tools, apps and dashboards from their models. And Param users create modern Rest Apis via Fast Api. For a Streamlit+Fast API example check out https://testdriven.io/blog/fastapi-streamlit/.

I can see how Pydantic could be supported by Panel. I.e., just as Panel already does for Param, Panel could accept a Pydantic BaseModel-derived class and read the metadata it needs to synthesize widgets, etc. from it. I'm not quite seeing how Param and Pydantic could interact, though; can you explain? Seems to me like it would be confusing to mix Param and Pydantic in a particular class, even if you prefer Pydantic's syntax for specifying types.

4. Add a real world example. Add a section with a real world example. My personal profile would simply need that.
   I work with traders so in my world the Black Scholes option pricing model is a great example.

Maybe we'd want two very different real-world examples? Black Scholes is fine as one of them, as long as it's a simple Param class that works well with Panel.

To-do items:

• Make a 2-5 min video that explains the "why" with a real world, practical example. It should be a walk through of a very interactive Notebook that can be downloaded by the user right next to the video, plus a link to Binder for trying it out.
• Link to the video from the introduction and probably home page.
• Make a 30-sec .gif video that just plays and immediately explains the Why to me and catches my attention.
• Link to the gif from the introduction and probably home page.
• Change __call__ to sum
• Consider whether to put a first example with only a single level of inheritance
• Add pydantic to Comparisons
• Consider adding Pydantic(PaneBase) to Panel, analogous to Param(PaneBase).

[MarcSkovMadsen]

Here is a video illustrating the concept.

param3.mp4

[MarcSkovMadsen]

and here is a faster version

param3x2.mp4

[MarcSkovMadsen]

I will make a PR with the notebook. But please consider giving me right to push to the repository like I have for Panel @jbednar .

[ea42gh]

I'd be happy to edit such a video!

The way I see it, this would involve

1. creating the notebook
   I advocate using folding for each of the sections:
   this would require each of the section/subsection titles be in their own markdown cells
2. multiple recordings of somebody explaining the notebook.
   Here, audio quality is the most important consideration.
3. I could then take these multiple takes, and edit them to create a video.

How would we get this organized?

[jbednar]

Cool! Yes, please do submit the notebook, e.g. as examples/intro.ipynb or examples/promo.ipynb and we can edit that until we're happy with it. Then we can record something with audio and go from there (and address the other to-do items here).

[MarcSkovMadsen]

I will also submit the Notebook ASAP and we can iterate on it. But maybe it would be an idea to write down and formulate the purpose and target audience of the material. That could guide us when discussing content, layout, format etc.

For inspiration on what @ea42gh can do with video check out this video that @ea42gh produced for panel-chemistry https://drive.protonmail.com/urls/0XQCDYYY84#Zd1ZRPWvIg2X

[MarcSkovMadsen]

Started a Promo Notebook PR here #487. Feel free to comment or contribute.

[ea42gh]

I have some suggestions for the documentation I'd like to make
since we want to produce videos.

E.g., using <br>$\quad$ to reduce line lengths,
adding additional subsections to create more of a framework for the audio,
changing font sizes.

What is a good way to cooperate on this? PR on top of PR seems a bit clumsy!

[philippjfr]

@ea42gh Happy to make you an external collaborator so you can push to @MarcSkovMadsen's PR.

[ea42gh]

@phillipjfr How does that work? Can you point me to some explanation I could read?
Does this cover it?
https://medium.com/google-cloud/pull-push-to-someone-elses-upstream-github-pr-6073ae5005e7

[MarcSkovMadsen]

I am perfectly confident you doing an iteration on the "draft version" I made.

For me the purpose is to make sure

1. Not so strong Pythonistas understand if Param can be useful for them and is worth their effort to learn.
2. Strong Pythonistas immediately understand what Param is about and understanding enough to actually start using it.

So anything that can make the notebook communicate better is key.

[philippjfr]

@ea42gh Now that I've added you (and once you accept), you will be able to clone the repo, check out Marc's branch (once he's pushed it to the param repo), and push directly to that.

[ea42gh]

@jbednar re audio/video, some thought should be given to consistent branding:

1. intro and outro visuals and possibly background music
2. color theme for annotations (bubbles, arrows, etc; design should yield good readability for text over background)
3. a consistent set of annotations and transitions

What are your thoughts?