Add Panel tutorials #5525
Add Panel tutorials #5525
Conversation
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #5525 +/- ##
==========================================
- Coverage 84.45% 84.16% -0.29%
==========================================
Files 299 301 +2
Lines 44677 45099 +422
==========================================
+ Hits 37730 37958 +228
- Misses 6947 7141 +194
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. |
|
Are you sure these are tutorials? If I look at https://diataxis.fr/tutorials/, tutorials should Lead the user through a series of successfull steps and help the user build something meaningful. Not explain anything. |
|
In all likelihood they will not be added to the docs in their current form, I mainly needed somewhere to put them for now. So no, these are not tutorials in the Diataxis documentation sense, at least not yet.
This is, I think, a mischaracterization, the point Diataxis makes is the explanation is not what they should take away from the material but rather just a means to get them to do something practical. The important thing is to get across how to achieve something, it is imo okay to explain plain facts, i.e. the that, but only as a means to get them to apply the knowledge. What absolutely shouldn't be in a tutorial is the why. Even for the current purpose my current material is just a start and I still need to make sure that the existing material:
This material will be the basis of a training course and once I've delivered it I'll see if and how we can adapt it to our docs or whether it'll be completely separate. Likely I will try to split each section into theory and practice and the practice part is what fits the Diataxis tutorial definition. |
|
That all being said I also struggle a lot here, my goal for this tutorial is to get someone to a relatively deep understanding of Panel in a relatively small amount of time. I realize this won't happen in one big session but will require revisiting these materials a few times. At the same time I struggle to see how a purely practical tutorial without anything stage-setting will be enough to get any understanding or proficiency. |
|
Perhaps, we should reframe these as course materials, rather than tutorials, and we shouldn't try to create both in one go. It's better to show less and have the users interested enough to explore on their own, rather than cram everything and have them completely lost. |
|
We currently have a pretty major problem in Panel's docs, for a new user there's a big hole after going through the Getting Started, that is definitely too short to learn how to build any kind of app that is not trivial. The User Guides we used to have served that purpose somehow, you could go through one after the other. With the How-To's, we've gained content that is useful for when you're working on an app and have already some knowledge, or when you look for something specific, but we've lost that learning experience, going through all the how-to's doesn't feel very natural to me (how-to's are also a better way to scale docs compared to the user guides, which is good!). There's really one thing you can do with Panel: build an app. The Getting Started covers that quickly, my vision is that we're building an advanced tutorial that users will follow when they're done with the Getting Started, decide to commit with Panel and/or embark on building a more complex app. It's going to be generic, because Panel is a generic framework and that's the HoloViz philosophy. In the future we can still add new tutorials, e.g. build a BI app, build a data app, build a machine learning app, etc. To have a nice advanced tutorial I believe we will need (not for this PR!):
We also need to figure out what exactly should go in the |
Are you suggesting that each tutorial section builds up one app step by step growing in complexity each time? |
Yes, even if that shouldn't be a strict rule, if there's a concept or example you want to include in a guide but that just doesn't fit in the final app. Having to build an app through the tutorial will help framing it, it will also be a nicer experience for those following it. They can go away with a complex app built based on what we consider good practices. (I believe the app you showed us the other day internally would be a good candidate) |
|
I've gone back and forth on that idea a lot, my concern is that it'll be very hard to do that well. It's very hard to slowly build up an app in a way that makes sense in terms of a pedagogical progression, i.e. the concepts that you want to teach first may not necessarily overlap with the first steps you do when building an app. It may be easier to simply build the full app and then pull out bits and pieces to allow the user to recreate those through exercises but I'm honestly unsure about that too. |
|
What about taking inspiration from some that are famous for good docs. Like Django, FastApi or Streamlit? |
|
What about taking inspiration from the Streamlit Guide. They start by introducing simple things. It could be layouts, Panes and templates. Dynamic layouts and Streaming with generators are also powerful and relatively simple. They can bring a lot of value already to users. Then later widgets, parameters, bind etc. |
|
My 2 cents: I think this will be super! :-) My main problem with https://panel.holoviz.org/ to learn Panel was that there's so much content that it's almost impossible to read it all, and it's very difficult to figure out a useful order in which to read pages under "how to" and "explanation" and the galleries. I got lost. What I like is how here I have 1, 2, 3, ..., 12 with a clear path. I can read through it all and learn Panel thoroughly in a weekend, or of course also omit topics if I don't need them. But it's finite and well-structured. Other docs I like for that reason (clear order and structure) is e.g. https://doc.rust-lang.org/book/ or https://shiny.posit.co/ I think teaching Panel by building a complex app and refactoring it over and over and learning new concepts is also fantastic. I would love to do such a course. But it's very hard to put together. I remember reading https://www.flaskbook.com/ years ago where this is done in Part II, and Part I is more like this tutorial introducing topics one by one with several small apps. So it could come later as Part II for Panel as well? |
|
I can only agree with you @cdeil :) We have certainly neglected tutorials a little bit too much (for good reasons! as we improved a lot the remaining content). I think an critical point is that when you have good tutorial/learning content, advanced/interested Panel users can own it more easily which enables them teach their peers better. For instance, if we have some good tutorials, I wouldn't be surprised to see some people leveraging them to produce videos for Youtube. |
|
One question I have is whether the getting started section is something separate. This is a tutorial focusing on getting started. Here every new user should get started to get the basic understanding. It should be very easy to identify as the tutorial for new users. The there is a separate tutorials page with other tutorials. Could be Panel topic specific tutorials, domain specific tutorials and maybe even links to some of the best external tutorials shared by the community as blog posts and videos? These tutorials are read when you need to start learning about some more complex topic. Could be ReactiveHTML, could be AI Chat interfaces, could be using Panel in Finance etc. |
I've wanted a |
philippjfr
force-pushed
the
tutorial
branch
from
6f5f272
to
1e42929
Compare
|
As inspiration for learning about a web frameworks features see https://eugenkiss.github.io/7guis/tasks |
|
Any chance to get this merged and available in the docs? It's inactive since over 2 months. Could it just go in as-is and then see incremental improvements moving forward? Let me know if there's anything specific I could help with - would love to see this in the docs and take some (admittedly limited) time to help with edits or review here. |
|
I'm merging tutorials 1-7 from above and will continue iterating on them. |
bindand eventually reactive expressions)depends, using thepn.Parampane andWidget.from_param.object.valueparameterListLikeandGridLike, contents can be replacedmargin,loading,width,height,stylesetc.--autoreloadon the commandlinepn.serve(i.e. latter has more control over routing)pn.state.locationandpn.state.session_argspn.state.user(assuming Auth has been configured)