-
-
Notifications
You must be signed in to change notification settings - Fork 516
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Enhance the tutorial #6215
Comments
My scattered and random thoughts about docs:
|
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.
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.
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.
This is really explanation material, comparing and contrasting the two, and we should link to that from the tutorial sections.
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. |
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.
I still think a Why Panel is good to have that highlights its strengths, and maybe even what it's not good for. |
Yes, the purpose should definitely be made clear. Just to summarize at a high-level:
|
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? |
Thanks @ahuang11. Really appreciated. I'm very much aligned with @philippjfr comment above. I have a few extra comments below.
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
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 |
I've added a section called Life Cycle Hooks that should contain |
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: |
No problem renaming. I just chose that name as Life Cycle Hooks are key components of any js front end framework to explain. |
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. |
Also, I think being more explicit with For example:
|
... helpful and engaging |
Some of my thoughts on things discussed in this issue:
|
I'm totally in line with that @maximlt. Thanks. |
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. |
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. |
The new tutorial is now in the
main
branch. I will collect my feedback here.Overall
Details
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
The Streamlit index have sections with titles that users will understand and much, much less text and teaching.
Take inspiration from the Django tutorial
Take inspiration from the FastAPI tutorial
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.
The text was updated successfully, but these errors were encountered: