Some manual pages are quite long. This makes them difficult to navigate in; the user needs to either scroll a lot or use search (either Ctrl+F or the manual site’s search).
The space is already occupied for subpages of two of the manual pages (namely of “Platform Notes” and “Card Templates”), and more subpages might be added once a page becomes too extensive.
It’s effectively the same as my original suggestion, but should be doable with the doc software. (I was thinking too complicated when I presented the “obstacle”).
I think we should err on the “atomic” side (just like with Anki cards). Ideally, the user will have to scroll as little as possible.
I could make a list of pages that are especially long (and thus probably worth breaking up), but it should be evident.
In my opinion, shorter pages are appropriate for manuals because:
Users often come to the manual with one specific question; so, they only need one or two specific pages. On the other hand, users who want to read the whole manual in one piece will not have much trouble: They’d only have to click more often, which I think is acceptable, or read the print version (> 200 pages of paper in my browsers ).
Everyone will benefit from a better overview and navigability. You can see where you are within the context of the whole manual, and where you might find more information related to what you are reading.
Right now, you’d need to keep scrolling up and clicking on the headline to switch back and forth between text and ToC. It’s even more annoying when you want to switch between two pages.
The hierarchy is preserved. You would still see which subpage belongs to which parent page. It’s not like it becomes a flat list of pages.
If I open the old version of the manual, I find it very enjoyable to navigate in. Although it is a single page, the sidebar ToC is atomic, it collapses and expands automatically, and it highlights the section I am reading.
Each extra TOC entry will require breaking that part of the text out into a separate file in a subfolder. I don’t have time to do that at the moment, but would be happy to accept a PR if you’re volunteering. Not all sections would be appropriate to split up - things like Leeches - Anki Manual probably don’t justify separate files.
).