Docs: Navigation menu wrap-up: About, Features and Advanced Features as Reference (Diátaxis)

[benjaoming]

This collects existing articles in the same menus with a bit of consideration of ordering of menu items, but otherwise not much more to it.

Notice that Read the Docs for Business is moved in #10007

Refs: #9746

---

📚 Documentation previews 📚

• User's documentation (docs): https://docs--10010.org.readthedocs.build/en/10010/

• Developer's documentation (dev): https://dev--10010.org.readthedocs.build/en/10010/

[benjaoming]

Created a directory here.

It's not immediately in use. But the intention was to have an actual collection of articles, spanning some existing items once that we start doing path refactors and redirects (which we have said not to do right now)

Because of DirHTML, this shouldn't make a difference right now.

[ericholscher]

This looks great to me to get the menu into shape for the big main merge.

[ericholscher]

💯

I think this page is what should replace https://docs.readthedocs.io/en/stable/hosting.html -- a really nice feature index with highlights of each feature.

Similar to our landing pages, a feature highlight, that drops into that feature detail... 🤔

[benjaoming]

Yes, when we introduced it, we said to start using it as the new index -- but we just postponed the design of the index for next iteration :)

I think the work to move the hosting features in as a description list is great, we can probably do that for other pages, too. But it's best to do in just one PR, otherwise we get Git conflicts galore :)

[ericholscher]

🔥

[agjohnson]

I noticed this on a few PRs that I've been pinged on, but the TOC menu seems out of order or like another level of hierarchy is needed or something:

"Explanations" have grown to dominate the TOC, and seem like less likely targets than the docs hidden beneath the fold on the menu. The long doc names also contribute here of course.

I haven't been following specifics of PRs here, so perhaps this was discussed, but is there plans to nest or reorder the TOC items under explanation?

[benjaoming]

@agjohnson there's a planning document about introducing a new TOC structure in the next iteration: https://docs.google.com/document/d/1LQXMUOAKBZ4RhAew2F4TCDp-QW7czH5Dq6BPxlyA_dw/edit#

In this document, we went over the first proposals of new sub-levels of Explanation and How-to, and we went far enough to get a good feeling... the remaning part will happen in PRs. As we all know, the hardest problem in computer science is "naming things" :)

[benjaoming]

@ericholscher I managed to quickly "dump" a list of contents in the about section, it needs a little extra love. But aside from that, the PR seems ready. You're welcome to make any changes necessary to merge it, otherwise I'll return to it on Tuesday ⏳

[ericholscher]

This looks pretty much ready.