Hi hi! This is a discussion-type question, so I’m trying to keep it out of GitHub for now.
The existing Qubes User Docs were created in Jekyll and are hosted on GitHub.
I had some more ideas (because I’m me) with regards to more opportunities to improve the usability of the Docs ToC page:
Creating an additional hierarchy of nesting (see above for what I have as Everyday Use, Templates, and Troubleshooting), and
Adding explanation text to some of the more cryptic items in this ToC—currently italicized in the below GDoc (see “Choosing Your Hardware” and “Troubleshooting”).
Is it an option to use the Text/URL syntax to change the user-facing names of hyperlinks, such that they don’t always need to be the same as the destination page’s H1? This one I could have poked at on my own to see, except I’m not yet fancy enough with GitHub to know how to preview Jekyll stuff in my browser.
For users “browsing” the docs and not just using Google, all three of the above feel important to help make the docs more navigable.
Minor clarification: Jekyll is what builds and serves the website. The documentation is just plain text files written in Markdown. So, the documentation was simply created (i.e., written) in text editors, not via Jekyll.
Funny story: One of the first things I did when I initially started working on the documentation many years ago was to make this sort of change. However, shortly after that, Joanna said that the docs were a mess and too hard for non-technical users, so she said that there would be just one flat list of doc pages with no further levels of nesting, and so it has been ever since… until recently. Recently, the localization overhaul had some side-effects, one of which was the subtle (re)introduction of a second level in the list of doc pages. Your proposal would add a third (and we’re back off to the races).
There’s also a technical issue here, which is that the current website code expects only the current two list levels. Setting aside, for a moment, the question of whether we should introduce that third level, doing so would likely require adding another loop in the code, probably inside of this one.
I don’t have a strong opinion on whether there should be deep nesting or a flat structure. I’d be interested in hearing opinions on this (especially any backed by empirical data).
Should be doable and might be useful.
It actually used to be this way, but I recently changed it so that the title in the doc index and the page’s h1 are both automatically generated from the title specified in the YAML frontmatter. You can read more about the change here:
Short version: Doc maintenance was unnecessarily burdensome before, since titles would get out of sync and have to be manually fixed all over the place. The new system greatly simplifies and automates things. I sense that you might next ask whether I’d be willing to change it back. Since I’m the one who would have to clean up the resultant mess, my answer is no.
Andrew: I am not trying to create a mess. Users do not consume metadata, they consume words on a page—and URLs as technical artifacts need to make sense, in the context of URL structures. Not for how users consume words on a page against the needs that brought them to that page.
My suggestions are rooted in how cognitive processes actually function in human brains. Not how we feel they should function.
Joanna is also not a UX practitioner, and was making her own best guess, I suspect. How things are done, matters much more than abstract concepts (2 vs 3 levels of list hierarchy, is abstract, as it removes presentation from the equation—and presentation also matters a great deal, in usability).
Also, fwiw—I would REALLY prefer to avoid using bulleted lists, too. I’m trying to make the docs better, within the constraints that currently exist. What I suspect Joanna was referring to, was the tendency developers have to overload bulleted-list type documentation pages. Yes, when each hierarchy of nesting has +10 items in it, and you have 3+ levels of hierarchies, it can get overwhelming. That is a bigger and harder to unpack IA problem, though, than any hard and fast rule “don’t have more than 3 levels of hierarchies.”