Do we need hierarchy/order for help topics?

Closing it as there's no reason to bring complexity of hierarchy into documentation

Now that this is close to being officially not an experimental module, sites are starting to want to use it to help with internal documentation. A big hurdle to using it is that the topics currently are all in a flat list on the main Help page, intermingled with all the other core and contrib module help topics. Adding some hierarchy and / or ability to organize the topics and navigate them would be extremely useful and I believe would make this module a lot more likely to be widely adopted.

This is what the out-of-the-box topics list looks like. As is, it is hard to read and as the list grows will become even more difficult.

What would be very helpful to have (some of these could likely become separate issues):

• The ability to customize the Help Topics page a bit
  • Group listed topics by site and/or module
  • Add the help search form to the topics listing page
• Parent/child relationship between topics
• Add a topic listing block that:
  • Lists parents, children, and sibling topics
  • Customizable block title?
  • Has its own twig template

For first stable we decided that having topics searchable is enough, but yes we'll need to deal with hundreds of topics

Thank you @Mindewen for your perspective and ideas!

What about enabling Layout Builder integration on for admin/help and provide a default layout which could be overridden by site admins?

- We could make each HelpSection plugin a block, which could be placed in a layout section.
- We add a Topic Category block plugin that creates blocks for each topic plugin prefix's first word and lists all topics with that prefix in that block. For example: book.about, book.configuring, book.creating, book.organizing would be listed in a "Topic Category: Book" block/. This effectively creates blocks for each module's topics, that would then be placed in the layout.
- These blocks (the 3 HelpSections-as-blocks and the Topic Category blocks would be placed in layout sections at admin/help for a default layout that is shipped with core.
- As contributed modules are enabled, their topics are enabled, a new topic category block is created, and it is either placed automatically in the Topics HelpSection. There would need to be a layout section designated as a catch-all for newly enabled modules. Or something.
- This default layout could be overridden and blocks re-arranged as desired.
- The admin-help layout could have a corresponding layout twig template that could also be overridden and customized by the site owner.

I have a client project where we're using this for internal documentation, but because we're only using it for internal documentation I just altered out all of the help topics that aren't provided by our custom module. This was an extremely brute force approach but so far was all we needed.

We add a Topic Category block plugin that creates blocks for each topic plugin prefix's first word and lists all topics with that prefix in that block. For example: book.about, book.configuring, book.creating, book.organizing would be listed in a "Topic Category: Book" block/. This effectively creates blocks for each module's topics, that would then be placed in the layout.

So to take book, if I had a contrib module called book_plus, I could do book_plus/help_topics/book.plus.html.twig and it would then show up in the 'Book' section?

One problem with this would be that system module's help topics currently have 'system' has the prefix, but they would probably need to be moved into different categories.

I'm wondering if we should add a 'category' to the front matter rather than relying on the prefix? So you could have 'User management' 'Regional and translation' a bit like the system admin sections?

As we have fields "categorized" it looks like good idea, IIRC there was some discussion to add kinda Tags