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?

[nickrsan (Nick S)]

I’ve been thinking about this too, separate from meta.discourse.org, but as a general need for the docs categories plugin. Landing on the index page is much better in many cases, and I think would clarify the sidebar contents for people compared with landing in the category and likely not noticing the changed sidebar until you’re in a topic.

An option in the plugin to enable it on a category would be great, so that in cases with incredibly long lists like mentioned here, you might disable it, but in others you might enable it

[nickrsan (Nick S)]

I dug into this a bit more today - I was considering if I wanted to make a pull request to add a setting to the plugin. When enabled, the setting would force direct links to the category to forward the browser to the documentation index for the category. While looking at existing work on the plugin, I came across a much larger rework of the features that’s in progress: FEATURE: Add visual doc category index editor by megothss · Pull Request #87 · discourse/discourse-doc-categories · GitHub

It seems like it’d be a great time to add this kind of optional functionality for using the documentation index as the category listing. At the same time, it might conflict with a “Simple Mode” that @sam is developing within the update. Sam, do you see the option I described above as something that might fit into your work on Simple Mode or the larger work in the PR to provide more options for building the index? It’d be really awesome to be able to choose the simplified column setup you’re developing or to just use the index topic. Maybe even ideally, the contents of the post display above the full, normal or simple listing of the category.