Enhance the tutorial

[MarcSkovMadsen]

The new tutorial is now in the main branch. I will collect my feedback here.

Overall

• [ ] To resolve issues we should refer to Diataxis Tutorial Guide, FastAPI Tutorial, Django Tutorial, Pandas User Guide and Streamlit Get Started
  • [ ] There is one tutorial. Not multiple tutorials. See FastAPI and Django
  • [ ] The tutorial is missing what is in the getting_started. See Django and FastAPI. Its fine we just need to refer to it.
  • [ ] According to Diataxis the focus on the practical activity and steps. We should not explain too much. To me this means we should remove lots and lots of text and have more steps and activities. For example the Components section is clearly not a section in a tutorial. Instead there is so much text. It needs a complete remake. The interactivity section can be an excellent explanation - but again its not a tutorial. I would not be able to give this to my colleagues or use at a conference and make them interested in Panel. Its a section you read when you have the interest, invested and is ready for more. Its like that every where. Its currently an explanation - not a tutorial.
  • [ ] We should guide our users to the order of the sections.
  • [ ] If the sections are made available as notebooks we should give them numbers so that the order is clear in a file explorer.
  • [ ] We should keep explanations short. And provide links to relevant sections in the Explanation docs for more info. Alternatively more clearly seperate the steps and the explanations. Make it possible to do the steps and learn from them. Skip the explanations if short on time or not relevant for the user.

Details

• [ ] We should explain the prerequisites to taking the tutorial
• [ ] We should explain how users get setup
  • [ ] We should provide a link to an easy to use cloud environment where users can run the tutorial. That will make it much, much easier for users and for us if we are running the tutorial at a conference.
  • [ ] We should make it easy for users to install the tutorial
  • [ ] We should add jupyterlite link
• [ ] Then follow the section order of the Streamlit Migration Guide. Its easier. Panes and layouts are not so hard to grasp. And users will start out being successful. Reactivity, widgets and binding is much harder to understand.
• [ ] You cannot start a section with the name Param and not even explain the why. That is not motivating. I would call the section Reactive Parameters, Parameters and events or just Parameters. And save it for later.
• [ ] Add a final section on deployment. I recommend making a practical deployment exercise where we deploy to hugging face spaces using the panel-template. This will give users a huge sense of success. And if we are lucky they would go ahead, share apps on hugging face and start sharing on social media.
• [ ] Remove the exercises. Or at least provide solutions. Otherwise it can get quite frustrating for users
• [ ] Add direct link to Jupyterlite in getting_started/index.md file to https://panelite.holoviz.org/lab/index.html?path=getting_started%2Fbuild_app.ipynb. That will help users find the relevant notebooks.

Outline

I think the tutorial should start at lower entry point. Learning about Param is advanced and might scare some people of. I think you can find lots of inspiration in the order of the Streamlit migration guide.

I would recommend an outline like below

MOVED TO #6243

Take Inspiration from the Streamlit Migration Guide

• [ ] Use section titles that will give users assocations
• [ ] Minimize section explanations
• [ ] Clearly outline the order of flow

The Streamlit index have sections with titles that users will understand and much, much less text and teaching.

Take inspiration from the Django tutorial

• [ ] Break sections into three: Getting Started, Tutorial, Advanced Tutorial.
• [ ] Clearly order the sections.
• [ ] Don't describe the sections in detail.

Take inspiration from the FastAPI tutorial

• [ ] Split into Tutorial and Advanced Tutorial.
• [ ] Explain how to use tutorial
• [ ] Explain how to get up and running with a working environment
• [ ] Consider whether FastAPI flow of 1) Make the user do steps 2) Explain what is going on makes most sense.

Conclusion

For now I would not mention in a release that there is a tutorial. Its simply not ready. We will disappoint our potential users.

[ahuang11]

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

[philippjfr]

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.

[ahuang11]

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.

[philippjfr]

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.

[ahuang11]

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?

[MarcSkovMadsen]

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.

[ahuang11]

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.

[MarcSkovMadsen]

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.

[ahuang11]

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

[MarcSkovMadsen]

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.

[ahuang11]

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.

[ahuang11]

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

[MarcSkovMadsen]

... helpful and engaging

[maximlt]

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.

[MarcSkovMadsen]

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

[philippjfr]

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.

[droumis]

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.