The 2026 Drupal Business Survey is open. Your response will help shape the future of the Drupal business ecosystem.Problem/Motivation
The current name of this module is "Configurable Help", but that doesn't fully describe what the module does. Main features of this module:
- Allows modules/themes/distributions to distribute multiple help topics with their extension; they can have dependencies
- Allows admins to edit/add topics, without knowing PHP
- Topics are arranged in a hierarchy/tree (loosely), with only topics marked "top-level" displayed on the main Help page to reduce clutter
- Related topics (link one topic on another's page)
- Behind the scenes, topics are broken up into paragraph-sized chunks for translatability, but the UI is similar to node body editing (text formats in one big chunk of HTML)
- (coming/future) Searchable [this may be in a separate module though]
Configurable Help only conveys the "Allows admins to edit/add topics" part.
Proposed resolution
Rename the module (both displayed name and machine name).
Proposed Names
- Extendable Help (extendable_help)
- Extensible Help (extensible_help)
- Advanced Help (advanced_help)
- Help UI (help_ui)
- Help Guide (help_guide)
- Topical Help (topical_help)
- Help Topics (help_topics)
Random thoughts on naming
Start the machine name and displayed name with the word "help" so that it's listed after the original help module in core/modules and in directory listings.
Don't call it Advanced Help, because
(a) I don't like the word "advanced" because it doesn't really tell you anything
(b) I don't think this module is necessarily "advanced"
(c) It would be confusing given that the Advanced Help module has existed in Contrib for years and years and people will be familiar with it if they used Views or Panels in Contrib in Drupal 6 or 7 (maybe 5 too, I am not sure).
Remaining tasks
1. Agree on a better name.
2. Change both the displayed name and machine name in the code, including changing function and class names, namespaces, etc. to be compatible with the new name.
User interface changes
The module's name will be different on the Modules page and in its help topics. Possibly some URLs and permission names will change.
API changes
This is a very disruptive change. Most functions, classes, interfaces, entities, permissions, theme hooks, render elements, etc. will be in different namespaces and/or have different names.
Data model changes
The config schema will probably have name changes, including the sub-schema for the topic body.
| Comment | File | Size | Author |
|---|---|---|---|
| #12 | 2921120-rename-help-topics.patch | 44.08 KB | jhodgdon |
Comments
Comment #2
andypostComment #3
jhodgdonI'm definitely open to changing the name... Let's see.
I called it Configurable Help originally because it gives site admins a way to set up a site-specific help system. Also it allows module/theme/distribution developers to save help topics as configuration items and distribute them with their extensions.
I wouldn't want to call it Advanced Help, because
(a) I don't like the word "advanced" because it doesn't really tell you anything
(b) I don't think this module is necessarily "advanced"
(c) It would be confusing given that the Advanced Help module has existed in Contrib for years and years and people will be familiar with it if they used Views or Panels in Contrib in Drupal 6 or 7 (maybe 5 too, I am not sure).
I like "extendable help" just fine. Gets across what I was thinking about...
Hm...
So...
If we make a base module and a UI module, then how about this:
The base module could be called Topical Help, because it provides a way for modules/themes/etc. to distribute one or more help topics, and they show up on admin/help in a section that is (currently at least) called Help Topics.
Then if we split off the administrative user interface from the base module, that module could be called Topical Help UI.
I'm not at all sure that splitting the UI off into a separate module makes sense though, because all of the administrative actions (collection page, edit, add new, lock, unlock, delete) are currently operations in the annotation of the entity. It doesn't really make sense to me to split it off into its own module if it means we have to make them just generic routes, or modify the entity, or some such thing. It seems like that would just add complexity.
I also think that many people who would want to have the basic Help module and this one turned on for a site, would also benefit from being able to create their own help pages for their site users, so I'm not sure that splitting off the UI would benefit many sites -- probably most big efficient production sites wouldn't be displaying any help at all?
Anyway, those are my thoughts...
Comment #4
andypostI meant to split that mostly in terms of moving display logic into core's help module (entity as well)
... but really few forms and routes are not a big deal for sure.
Topic help - I like the idea!
Let's get more opinions on naming cos I'm sure it matters)
Comment #5
jhodgdonYeah, when I originally proposed this (prior to original D8.0) it was part of the core Help module. We can certainly consider moving into the core Help module eventually, but for now I think it needs to be separate. The Text Sections stuff should be in core/lib/Drupal/Component I think also... I tried to get it in there at one point but. Well. Without advocates and help and reviews, these things do not happen in Core.
THANK YOU for your energy, enthusiasm, coding, and reviews, is what I am trying to say! VERY much appreciated. :)
Comment #6
amber himes matz+1 for Topical Help (help_topical).
I like the idea of starting the module name with the word "help" so that it's listed after the original help module in core/modules.
Other ideas...
Help Guide (help_guide)
Help Topics (help_topics)
Comment #7
jhodgdonWe need to revisit this, and update the code/docs for this before we get the Core patch done, I think? Upping status to Major.
Comment #8
jhodgdonUpdating the issue summary with ideas that have been proposed here, and summary of discussion points.
We really need to do this. It is the only blocker to getting this into Core as an experimental module, and it's MUCH easier to do it now rather than changing it later.
Comment #9
MixologicPerhaps there are alternatives to the word "Help"? I have connotations associated with that word that says Im lost, stuck, or want somebody's assistance.
Guides/guidance
Instructions
Docs
Or, maybe we could get weird and use emoji's: help_❓_guides
Comment #10
jhodgdonHm... That's an interesting suggestion. But I think since this is in-site help, most people would look for a link/button/etc. that says "Help" on it, rather than Documentation, Guide, or Instructions?
Comment #11
jhodgdonThere were a few comments on Twitter (I tweeted about this issue):
@dawehner: Maybe make it clear it's user documentation?
@herbdool: I like Help Topics
Comment #12
jhodgdonHere is a patch that changes the name of the module to Help Topics, and the machine name to help_topics.
All tests pass locally.
Comment #13
jhodgdonOne note: I didn't make a hook_update_N for this. If someone was using this Sandbox module and wanted to update to this patch (if committed), they would need to uninstall the existing module, delete all the code, get the new module and put it in help_topics directory (not config_help any more), and install it.
And before doing that, they would need to export any help topics they had written (using the Config Manager core module or Config Update contrib module), and then they could use single configuration import to import each of them again.
Comment #14
jhodgdonOne more note: This is the last blocker to getting this module into Core as at least an Experimental module!! So, reviews are most definitely welcome!!
Comment #16
jhodgdonI decided to go ahead and commit this patch to the Sandbox, since (a) it works and (b) the tests pass locally and (c) the new name Help Topics had reasonable support among the people who took the time to comment either here or on Twitter.
I'll also update the Core patch. And the project page and release notes (see #13).
Comment #18
jhodgdonThe latest core patch had 3 very minor coding standards messages, so I made another commit against this issue rather than filing another issue.