What should the homepage be for doc categories?

[mcwumbly (Dave McClure)]

When you click on Documentation > Site Management, I wonder if it should it bring you to the index instead of the latest topics.

Or maybe it should being you to some other “overview” topic you specify?

We had been linking to the index directly in category descriptions to make it more discoverable:

related discussion

@manuel

@hellekin

BUT Subwiki “index” links go to a category instead of the index topic (at least in the case of “Developer wiki”) which requires another click to access the one-shot resources where you can Ctrl+f.

That’s just how the default category boxes work right now. We could probably change the default behavior. Though I wonder what’s the intended experience in our documentation categories. It seems the index was added with the category banner in mind, rather than the category box:

At the same time the index topic stays pinned to the top of the topic list, it doesn’t automatically un-pin when the index topic is read. So we’re duplicating this index quite a bit: In the first place it’s meant to generate the sidebar menu. Then we pin it to the top of the topic list. Then we add a link to it to the visible category description.

I think we could actually drop the link from the description in the documentation categories.

@mcwumbly

@manuel

At the same time the index topic stays pinned to the top of the topic list, it doesn’t automatically un-pin when the index topic is read.

Hmm… that’s not my experience.

But yeah, if it was working for me that way, then I think I’d see less of a need for the index to appear in these descriptions.

Regardless, this makes it clear the link is a workaround for a usability gap with our new docs plugin.

Or maybe it’s fine as is? Perhaps that’s redundant given that the index is already in the sidebar, but something feels a bit off to me about the current design in two ways:

• the index itself can be hard to find
• the latest topic list feels a bit disorienting compared with the way browsing documentation works once you’re in a given topic

[manuel (Manuel Kostka)]

I wonder if the index gives a better entry to the documentation. The problem I see is that neither the index page nor the sidebar make it easy to actually scan and navigate the documentation topics:

Not sure if there’s an obvious solution? There are patterns for better sidebar layouts from existing documentation platforms. But would these improve our case without doing more work on the actual organization of topics? They might not work well for the community wiki in general.

Maybe a right sidebar that has more of a table of content layout, rather than the current narrow left sidebar, would work better?