Best UX for a documentation "book" in a website format, specifically dividing it into chapters and how the navigation works?

Question

I am working on implementing a custom programming language, and am inspired by documentation examples from the web:

• Vercel
• Readme.com
• Rust Lang

You'll notice that the navigation on all of these has nesting, but it appears only 3 levels deep max. I've noticed this I think across many other examples. Rust has a flat URL structure, but Vercel nests the URLs https://vercel.com/docs/concepts/observability/monitoring.

I am working on a "book" for this custom language, and there is a lot to it. It is sort of like Ruby on Rails for all intents and purposes. (Rails guides are also flat).

I have so far only had to go 3 levels deep, but I can imagine going 4, 5, or even 6 levels deep. You can imagine how the Jewish Bible is organized as Tanakh > Torah > Genesis > Chapter > Verse. This can also be part of a greater collection, making 6 layers.

How would you show this up-to-6-layer navigation in the sidebar, as nesting the list items won't work. Would you hide some of it based on context, or what would you do to create a good UX? I like just having it on the left and the chapter/page on the right, but you can offer suggestions on how to change that if you'd like too. Mainly wondering how to organize the nav to handle deeper nesting.

Answer 1

You generally want to avoid doing massive and deeply nested navigation trees in favor of an overview page of topics, where the topics only are 1-2 levels deep.

The Jewish Bible example you linked above actually shows exactly this: Tanakh is the overview page, Torah is a section in this overview, Genesis is a single topic you can click into and drill down into the chapters and verses. And while down in the chapters and verses, the overarching structure of Tanakh and Torah is not important and doesn't need to be shown.

From the standpoint of organizing things, it also allows you more flexibility: With a full-on tree you may run into situations where an item may be part of category A and B. For example, saving a file may be part of a "getting started" category as well as a "the file menu" category. In a tree you'll often need to decide between the two and end up with much confusion as to why two closely related articles are on completely different branches, but if you keep things as standalone topics, you just can show the same article in both topic navigations.