Documentation structure

[ed2050]

Continuing the discussion from #1778 -

Proposal

The nicegui docs are great in many ways, but could use more structure. Something like this, where numbers indicate a tree structure of nested pages):

1. Nicegui Overview - each page in this section is a brief intro to basic concepts. No complications, no styling, no optional params. Just simple concepts and very brief examples.
   1.1 Adding Text
   1.2 Getting User Input
   1.3 Displaying Audiovisual Content
   1.4 Displaying Data
   1.5 Page Layout
   1.6 Styling & Appearance
   1.7 Actions & Events
   1.8 Configuring and Deploying
2. Text Elements
   2.1 Label
   2.2 Headers
   2.3 Paragraphs
   2.4 Links
   2.5 Markdown
   2.6 HTML
   2.7 Mermaid Diagrams
3. User Input Controls
   3.1 Button
   3.2 Toggle
   3.3 Slider
   3.4 ....
4. Audiovisual Elements
   4.1 Images
   4.1.1 Captions and overlays
   4.2 Icons
   4.3 Avatars
   4.4 Audio
   4.5 Video
5. Data Elements
   5.1 Table
   5.2 Chart
   5.3 Plot
   ...

You get the idea. With this structure, everything in section 1 would be new pages. Much of it could be borrowed from existing content, like the doc pages or Features section, but simplified. Just barebones concepts and examples to show how nicegui works, without optional args and complications.

The other sections 2 through ... could be pretty much the existing doc pages, with a few tweaks (eg. moving icons and SVG to the audiovisual section). Top level numbered pages like 2. Text Elements could be the existing top-level doc page, but trimmed to just the Text Element items. Preserving the current docs page, but splitting each section into a different page.

The subnumbered pages would be the existing "See more" pages like the button page. These pages could be autogenerated from the code as they are currently. With room for other improvements on them as suggested in #1778.

Advantages

This structure would help in several ways:

• Improved navigation, letting users explore just the section they currently want. Current docs page is a lot to scroll through.
• Easier to locate content. To find docs on markdown, I would click Text Elements then Markdown. Instead of the current setup, where I have to scroll up and down the long left nav bar hunting for the Text section and the markdown link.
• Surfaces more introductory material in the first section that is currently buried at the bottom of docs page (events, pages, lifecycle, etc), without going into full details.
• Provides a better introduction / overview to basic concepts of nicegui in section 1, then provides details in later sections.

Splitting up the current doc page would also help a lot with load times. When I load the doc page it takes several minutes for all the example cards on the right to load and noticeably spins up the fan on my machine. Having fewer items per page (one page for text elements, one page for data elements, etc) should noticeably improve load times and cpu load.

Open issues

Some of the items on existing doc page require some thought for where they fit best in this structure. For instance, Static Files, Media Files, and API Responses all have great info, but it's not clear whether they should be grouped together under Routes (which isn't very descriptive unless you're thinking like a network engineer) or whether they can be moved to other sections (Audiovisual would be a natural home for Media Files).

Auto-context is a fundamental concept that should be surfaced much earlier in the docs. You can't compose complete pages until you know that every element can be nested using with. The overview section should discuss this somewhere.

Docs could use more discussion of how refreshing works. After reading the docs I still don't have a clear picture of exactly what triggers a refresh of an element and how that refresh happens. I read the Refreshable section. It's entirely possible I missed something elsewhere, but that's kind of my point - it's not easy to find where else refreshing is discussed.

Conclusion

This proposed structure makes the docs easier to understand and navigate. It mostly preserves the existing content with minimal changes (splitting up existing sections into separate pages, reassigning a few elements to different sections), while adding a new overview section to orient users. There are some open details to sort out, but shouldn't require a major overhaul of existing content or how docs are generated. Giving a bit more structure helps organize the material so users can follow it better.

Happy to discuss further if useful. Hope this helps.

[falkoschindler]

Thanks, @ed2050, for this great proposal! I really like the idea. It would definitely help our users navigating the documentation. Let alone the reduced server load when splitting the page into smaller chunks. We're currently working on version 1.4.0, but after that this could be the next big thing to tackle.

A few questions:

1. How would the main documentation page look like, i.e. what is the entry point?
2. How would the menu look like? I guess it would show the complete tree with only the current top-level node unfolded.
3. How would page "1." would look like? In analogy to the other top-level pages it could show the first paragraph/code example per subsection. Navigating to, e.g., 1.1 would open a new page with more content.
4. How would page "1.x" look like? "Adding Text" could touch concepts like auto-context etc. But what are "core concepts" of "Displaying Data"?
   I wonder if the structure or "1." should be independent of the other top-level sections. We could start with a page about auto-context, continue with a page about frontend-backend communication and so on (see also "NiceGUI Fundamentals"). I don't see the need to mirror the structure of the remaining documentation.

Anyway, I'm really looking forward to working on this idea! 🙂

[ed2050]

Thanks falko, good questions. I have some ideas, but they need fleshed out more.

When do you expect to release version 1.4?

I'll think over the issues you raised, perhaps make an outline of some pages as I envision them, and fill in content to start with. I might even figure out how to do a pull request and put some material in git for you to consider.

[falkoschindler]

Sounds good!
I hope we can release 1.4 by the end of October.

[ed2050]

Hey @falkoschindler looks like you're ahead of schedule. I see 1.4.1 was published to pypi Oct 26. 😄

I haven't forgotten about the docs. See my proposed overview section here. I didn't complete it, but did do the first few subsections as a template for the rest. The readme page will guide you through the material.

Based on other discussions here and issues I ran into developing my apps, I changed a few subsections to cover topics that beginners run into. In particular, a section on bindings (which is covered late in existing docs) and managing components (not covered explicitly anywhere as far as I can tell). There may be other important concepts I forgot or haven't run into yet.

Basically, the overview should give you all the tools and concepts to build a nicegui app. Other sections (existing docs) give details of each element, once you know how to put things together.

Adding an FAQ section / page may also help. Some quick answers showing how to do certain things that aren't obvious from the docs. Like how to set colors on buttons. 😄

Hope this helps. Let me know what you think.

[falkoschindler]

Thanks a lot, @ed2050! This is quite an impressive work!

I'll try to integrate it as soon as I find a few hours to spare. It should be pretty straightforward given your contribution.

At the moment the monolithic documentation page is stressing our servers. Therefore splitting it up into smaller pages has very high priority.

[ed2050]

Happy to help. If you like, I can review and make suggestions to sections 1.4+ once they're drafted.

If you need a quick fix for server load, you might split the existing docs into separate pages to publish right away, and add the overview section later. Copy editing takes time.

Navigation structure

I've been thinking about your navigation structure question. You suggested a tree navigation, I'm guessing in a left panel similar to current docs. That could work - with some caveats.

Trees are nice when they aren't too big. If it's a few items and you can see most of the tree at once, great. Otherwise, trees can become unwieldy. Like the MS VBA docs; easy to get lost several levels down and doomscroll.

With that in mind, here are a few suggestions for navigation:

• Don't open the entire tree at once. Open the section the user is currently in, and leave other major branches closed. Eg. if I'm in section 1.4 of Overview, then all the Overview section can be expanded while sections 2+ only show the top level by default (obviously user can open more if desired). If I'm in section 3.3 Sliders, then Section 3 can be expanded and other sections closed.
• Expand all and Collapse all buttons would help. Sometimes you don't know where in the tree to go. If I'm looking for ui.notify, I wouldn't think to expand the Layout Section.
• In Overview section, links to next page at bottom are helpful. Keep users progressing through content in order. For other sections, next page links may not make sense. Most people probably won't read through all of Section 2 in order, then all of Section 3, etc.
• For the top-level section pages like 3. Controls, a visual index would be great. The page can list and link to each component in that section: 3.1 Button 3.2 Slider 3.3 Checkbox. With a screenshot next to each one showing how it looks. That instantly shows users what some of the less familiar items are (like Carousel) and aids visual memory for faster searching.

I could do a mockup of a section page if it helps. Though I expect you'll auto-generate those.
Wishing you luck.