Excessive number of DOM elements in table of contents #4063
Comments
|
It runs fine for me on Firefox on my laptop, but really it needs to be readable on a Pi 3 etc. I agree this doesn't need to be a single flat table of contents, and we could split the hierarchy across multiple pages to reduce the number of active DOM elements. |
|
Just to add that I am using Chrome on a Dell laptop, with 32GB of RAM. |
|
Is there a relationship between the displayed TOC depth and keys reachable from the search box? |
|
Looking at a built
|
No, what is available in search is dictated by what Algolia Docsearch crawls out of the actual page content. |
|
It's worth noting that on sufficiently wide screens, there is a second table of contents specific to the current page shown on the right, e.g. 
|
|
From a usability PoV, I think it'd be okay to reduce the depth of the LHS navigation menu, as long as the RHS navigation menu retains its current depth. Personally, I tend to navigate the site by using the menus rather than the search box, so reducing the depth of "clickability" would make the documentation much harder to navigate IMHO. Although I guess an alternative approach might be to have the current menu-depth only shown for the page you're currently looking at, and the ToC could then show a reduced depth for the other pages? (which I guess means that you'd need a different ToC per-page, and I dunno if that would harm cache-ability?) |
|
seems reasonable in the shortened version |
|
Despite reducing the left-hand table of contents to 26% of its former size, @JamesH65 (and others via email) are still having issues given the Hardware page still has over 39,000 elements that need their styles recalculating as the page loads. While I can try to further whittle down the markup in the table of contents, there are over 33,000 elements in the main page content itself. @lurch made reference to it being a conscious past decision to format these parts of the site as a few, single, very long pages but is this something we'd revisit? As far as I can see, postprocess_doxygen_adoc.py is actually responsible for splitting the doxygentoasciidoc output of a single [#group_hardware,reftext="Hardware APIs"]But perhaps it could be modified to break each inner group out into its own page, e.g. a page for For perspective: if we did that, the current group with the largest number of elements is |
|
To clarify further, I believe Paul is talking about https://www.raspberrypi.com/documentation/pico-sdk/hardware.html |
|
I have always hated (and that is not too strong a word) the move to massively long pages of information, so anything that makes them shorter is OK with me. |
@JamesH65 flagged that the Hardware page is extremely slow in his browser even going so far as to crash it.
Looking at the structure of the page, it has over 50,000 DOM elements (for reference: Google Lighthouse will error if you have more than 1,400 elements on a page). While we'd expect a lot of elements as the Hardware section of the SDK is very long, looking at the table of contents alone reveals 12,858 elements and this appears on every single page. Digging a bit more, the table of contents seems to have 1,242 entries when fully expanded so that's the absolute minimum number of elements we would need to render it.
We can look at simplifying the markup for the table of contents but can we actually reduce the depth the table of contents goes to, e.g. to top-level sections only (e.g. "Getting started with your Raspberry Pi") rather than sub-sections (e.g. "Getting started with your Raspberry Pi - Power supply")? The theory being that would drastically cut down the size of the table of contents without also rewriting its markup.
The text was updated successfully, but these errors were encountered: