Enhance the tutorial about panel HOT 17 OPEN

Some of my thoughts on things discussed in this issue:

• In the end, Diataxis is just a framework and we're free to adopt it the way we want. I think adopting a framework really helps both our users and ourselves! The framework will guide me when I add some new documentation. It'll be easier for me to know where and how I should write this new content. Before, it was just all a mess of user guides. Diataxis appears to be a popular and good documentation framework (TBH I don't know any other), it sounds reasonable to adopt it, we're past that anyway :)
• I haven't seen many mentions of the Reference quadrant of Diataxis, let's not forget it. It's as important as the other ones if not more, especially in a library like Panel that has a large code base.
• Links, links, links! We should link more between pages, this is the way to avoid repeating ourselves too much because repetition makes it so much harder to maintain good-quality documentation.
• I would prefer the "Learn the basics" tutorial of Panel to stick to some of the basics so it's not too long and is suitable for most Panel users. Panel apps can be any sort of apps, from a simple set of widgets and a view in a notebook (not even served) to a super complex multipage app with auth and all the bells and whistles. I'd keep the suggested sections for the "Advanced tutorial", like sections on generators, caching, life cycle hooks, etc. Of course, let's make it clear (e.g. landing page) that Panel is a very powerful framework so users know they can always improve their apps. But let's start with the basics.
• Once the table of contents of the basic tutorial is established, I'd recommend working on it section by section, with a PR per section. I found the previous doc overhaul difficult to track and review. This is also a core value of Diataxis, you don't have to re-factor your whole doc at once.
• I think some of the sections covered by the Tutorials will already have an How-To. Because we basically moved all the former User guides into How-Tos while I guess it should have been a mix of Tutorials/How-Tos/References. I think it wouldn't hurt to remove How-Tos if their content is already covered in the tutorials and/or references. I find the large number of How-Tos and their nesting quite difficult to navigate at the moment.

from panel.

Yes, the purpose should definitely be made clear. Just to summarize at a high-level:

• Tutorials are Learning oriented: A user new to Panel should be able to go from zero to proficient simply by following the material from start to finish.
• How-tos are Task oriented: A user building something with Panel should be able to go here if they are trying to add a particular piece of functionality or figure out how to do a specific thing.
• Explanations are Understanding Oriented: A user should go here to understand the reasoning behind why something was designed in a particular way, understand the tradeoffs between different approaches and get more context about various features.

from panel.

Right, but Panel users aren't js front end devs (that's why they're using Panel, or that was why I started using Panel), so I think we should cater language towards Python devs with no frontend knowledge. You could definitely mention "Life cycle hooks" inside the page though, but I think the section name should be crystal clear to everyone so they visit the page.

from panel.

Also, I think being more explicit with easily efficiently and flexibly in the titling can be helpful

For example:

 Indicate busy-ness with loading indicator
 Show activity on the fly with generators

from panel.

... helpful and engaging

from panel.

My scattered and random thoughts about docs:

1. At first glance, Tutorials + How-To + Explanation is unclear to me, and a lot of material seems duplicated.
2. Lots of the docs feel quite wordy (kind of like academic papers?). I agree with Maxime's comment about FastAPI "It's written in simple English, with short and easy-to-understand sentences". Maybe we can use ChatGPT to reword concisely?
3. I would really like a How do I... page, i.e. table of contents / cheat sheet, https://docs.xarray.dev/en/stable/howdoi.html or a revamped cheat sheet for Panel (the current one doesn't feel like a cheat sheet at all; matplotlib has good ones).
4. "Add interactivity easily and efficiently: pn.bind" and "Add interactivity flexibly: .rx" seems confusing to me; I think we should have one page that explains both of these, and when to use which one. In fact, I think a lot of these headers, if they are prefixed the same, should be under the same page under sub-sections.
5. Maybe we should have a dedicated Why page (or extract it from the home page like xarray--what's the benefit of using Panel over Streamlit, or even like React + FastAPI. To me, I think Panel shines in its ability to make apps that visualize big scientific data interactively, using just Python.
6. I don't think these should be considered advanced: "Scheduling tasks: on_load, globally" and "Improve performance by using async and threads". Getting started with building performant / responsive app is a priority because if the app isn't efficient or responsive upon visiting the page (i.e. seeing a blank screen with no indicators of loading), not many people will stick around for long to see it finally load and use it.
7. We should have an awesome-panel built in to the docs. Just external links showing cool things others have done with Panel

from panel.

Thanks @ahuang11, appreciate your input. I'll respond to a few items but would also like to keep the focus specifically on the tutorial section of the docs.

At first glance, Tutorials + How-To + Explanation is unclear to me, and a lot of material seems duplicated.

Review Diataxis to see the purpose of each type of documentation. Duplication is not something I'm particularly concerned about, the same material can be presented in multiple forms for different purposes. That said we should make sure the line between tutorials, how-to and explanation does not become fuzzy and I think some how-to material does straddle that line now.

Lots of the docs feel quite wordy (kind of like academic papers?). I agree with Maxime's comment about FastAPI "It's written in simple English, with short and easy-to-understand sentences". Maybe we can use ChatGPT to reword concisely?

Yes, this is a skill I will have to learn. I think it's a style that I've learned by nature of coming from academia but also have to some extent copied from @jbednar. I think it's fine for explanation section but not for the learning oriented Getting Started and Tutorial sections.

Add interactivity easily and efficiently: pn.bind" and "Add interactivity flexibly: .rx" seems confusing to me; I think we should have one page that explains both of these, and when to use which one

This is really explanation material, comparing and contrasting the two, and we should link to that from the tutorial sections.

Maybe we should have a dedicated Why page (or extract it from the home page like xarray--what's the benefit of using Panel over Streamlit, or even like React + FastAPI. To me, I think Panel shines in its ability to make apps that visualize big scientific data interactively, using just Python.

We do have the technology comparisons: https://panel.holoviz.org/explanation/index.html#technology-comparisons

But yes, a overall section on Why Panel is good too, but this is definitely explanation material.

from panel.

Review Diataxis to see the purpose of each type of documentation

I guess coming from the perspective of someone using the docs, they should not need to know what Diataxis is, and they should be able to immediately discern the purpose of each section, so I agree with your next point.

That said we should make sure the line between tutorials, how-to and explanation does not become fuzzy

I still think a Why Panel is good to have that highlights its strengths, and maybe even what it's not good for.

from panel.

Great! That's a really good concise overview of the sections, and can be mentioned at the top of a new Learnings section.

Perhaps Explanations can be under some Advanced section; I don't think users should go there until they go through all the other sections?

from panel.

Thanks @ahuang11. Really appreciated.

I'm very much aligned with @philippjfr comment above. I have a few extra comments below.

"Add interactivity easily and efficiently: pn.bind" and "Add interactivity flexibly: .rx" seems confusing to me; I think we should have one page that explains both of these, and when to use which one. In fact, I think a lot of these headers, if they are prefixed the same, should be under the same page under sub-sections.

Having very long sections makes some things harder. Like for example selecting a sub set of the tutorial sections if time is limited or the session is somehow focused.

For example in the serve.md section I have not currently taught people pn.state.served or --index which I always use. --index because I work behind a reverse proxy (jupyter hub) and enables me to click localhost:5006/app links in the terminal. Otherwise all the panel .css and .js cannot be found by the app. In addition pn.serve and pn.show is also relevant. I have not included that (yet) because I fear its too much. Users arrive to create awesome panel apps. Not to learn to serve them in many different ways.

6. I don't think these should be considered advanced: "Scheduling tasks: on_load, globally" and "Improve performance by using async and threads". Getting started with building performant / responsive app is a priority because if the app isn't efficient or responsive upon visiting the page (i.e. seeing a blank screen with no indicators of loading), not many people will stick around for long to see it finally load and use it.

For me this is also core material. I need this to know how to create performant apps. I was just a bit worried that it could scare of some users.

from panel.

For me this is also core material. I need this to know how to create performant apps. I was just a bit worried that it could scare of some users.

I think async could be in advanced, but onload probably should be introduced early.

from panel.

For me this is also core material. I need this to know how to create performant apps. I was just a bit worried that it could scare of some users.

I think async could be in advanced, but onload probably should be introduced early.

I've added a section called Life Cycle Hooks that should contain onload.

from panel.

What other content are we putting in that section? I'm wondering if we should rename that? Life Cycle Hooks doesn't mean much to me (as someone with mostly just Python knowledge).

Also the other sections start with a verb.

I think it could be put under:
Improve performance: onload

from panel.

What other content are we putting in that section? I'm wondering if we should rename that? Life Cycle Hooks doesn't mean much to me (as someone with mostly just Python knowledge).

Also the other sections start with a verb.

No problem renaming. I just chose that name as Life Cycle Hooks are key components of any js front end framework to explain.

from panel.

I'm totally in line with that @maximlt. Thanks.

from panel.

Same, really appreciate everyone's thoughtful commentary. I'm quite happy to keep a clear basics and advanced separation, that said, as long as the titles are simple to understand and descriptive people can and should feel comfortable skipping a tutorial section.

from panel.

Once the table of contents of the basic tutorial is established, I'd recommend working on it section by section, with a PR per section. I found the previous doc overhaul difficult to track and review. This is also a core value of Diataxis, you don't have to re-factor your whole doc at once.

I completely agree with this. I think it's counterproductive to make a comprehensive new multipart multitutorial the highlight of a new release. It would be better to just make small, consistent steps in this direction. I already struggle to comprehend the various discussions, PRs, and status of this recent effort, and that makes me hesitant to weigh in.

from panel.