Documentation is always one of the top concerns about Drupal, in surveys. Also, the help system within Drupal sites consistently shows up as having problems in usability testing -- it doesn't really help users figure out how to accomplish the tasks they are trying to accomplish. Here, we are proposing to improve the in-Drupal help system.

This needs to be done in Core. In past versions of Drupal, there were contrib modules (such as Advanced Help) that attempted to fix some of the problems with the Core help system, but they were not widely adopted. Getting the improved help system into Core would provide an officially-sanctioned way for Contrib maintainers to provide better help with their modules, themes, and distributions (and for Core to provide better help for itself), rather than hoping that people adopt a system provided by a contrib module.


The current Help system in Drupal 8 hasn't changed much since Drupal 4.6. How it currently works:

a) Modules can implement hook_help().

b) There are two different things you can do with hook_help():
- (1) Provide page-level help for an admin page, which is displayed in the Help block when that page is active.
- (2) Provide a module help page. Links to module help pages are listed at admin/help, and when you click on a link, you see the full page.

There are several key features that the current system lacks that keep it from being a very useful help system.

Quick summary of desired features

Features that would make the help system more usable:
a) Help should be oriented towards goals/tasks (things the user would want to do), not organized by module.
b) There should not be limitations on how many topics a module provides (and themes/distributions shoudl be able to provide them too).
c) There should be a way to have cross-links or "related" links between topics.
d) There should be a way for a site builder to add site-specific pages to the help system, for content maintainers and other users.
e) It should be easier for a non-coder to contribute help topics (currently they have to edit PHP to do so).
f) Help should be searchable.

Lower-priority but still desirable features:
g) A glossary of terms could be helpful, especially if module developers and site builders had an easy way to add individual terms to the glossary, and the glossary page(s) would automatically be compiled from the supplied terms.

Development concerns:
h) The old help system uses a hook instead of a more Drupal-8-like plugin system.
i) We need to make sure the help text is localizable using our current systems like -- therefore its text should be broken up into translatable strings no longer than a paragraph. See also #1885192: Field locales_source.source is not suitable for long texts and huge config objects -- this is not only desirable but necessary -- long topics definitely need to be broken up into smaller strings.

A more detailed list of desired features

Note: Skip reading this section if you already know enough about the desired features from the summary list above. But the code names here are referred to occasionally below.

  • [non topical] Each module can only provide one main help page for the admin/help listing, and you'd need to know what each module does to find help for its functionality, or read all the topics (and they're just listed in alphabetical order). A more ideal technical writing system would let modules, themes, and profiles (instead of just modules) each provide multiple topics, separated into tasks and concepts, oriented towards things a user would need to know (concepts) or do (tasks), and organized into sections and/or hierarchically. This has been filed as a separate issue: #2516902: Introduce a visual hierarchy to the help page.
  • [no search] There is no way to search help.
  • [markup] Markup is being provided inside hook_help(), especially for the module help pages, via concatenating translatable strings with HTML tags. Normally we don't want modules to provide specific markup for pages, but in this case they need to provide headings and bullet points and the like. This has been filed as a separate issue: #2188753: Get rid of hard-coded markup in hook_help() implementations
  • [authoring] The current hook_help() syntax is difficult for Documentation writers, who may not be PHP programmers. This is also mentioned as a problem in #2188753: Get rid of hard-coded markup in hook_help() implementations.
  • [cross-links] There is not a great way to cross-link to other topics. Currently this is done with PHP code (to make sure the other module is enabled) and placeholders for the URLs.
  • [code] hook_help() is used for two different purposes, and it's kind of a mongrel: the module help pages are specified by responding to a fake path/route, which is a little bit weird. Also, hooks are outdated in general. We have moved many hooks and page generators into plugins, controllers, or YML files.
  • Note: This has been fixed in Core, since the Help page now allows other help providers, such as the Tour module and potentially contrib modules, to list their topics on the Help page. [limited list] There is a core Tour module that provides a different type of help, but tours are not listed on the admin/help page either. Contrib modules may also provide some form of help, but they're not listed either.
  • [must enable] There is no way to see the module overview pages without the module being enabled first. This has been filed as a separate issue: #2587469: allow hook_help to run on modules which are not enabled.
  • [no admin] There is no way for a site builder to add pages to the help, except by writing a module to implement hook_help(). This would still not let them use the Help system to build help pages for content editors or other site users, since it would still be one page per module.
  • [glossary] It might be useful to have a glossary of terminology that modules/themes could add entries to. This is a separate issue: #2701289: Glossary to extend the Help system

On the other hand, there are some desirable aspects of this system that we may not want to lose:

  • [many strings] As discussed on #1918856-45: Put each module's help into a separate Twig file, we do NOT really want entire help topics to be one big string, because fixing one typo would invalidate translation for the entire topic... at least until/unless has some "fuzzy" logic that would preserve the old translation somehow. See also #1885192: Field locales_source.source is not suitable for long texts and huge config objects -- this is not only desirable but necessary -- long topics definitely need to be broken up into smaller strings.
  • [php code] Many of the hook_help() implementations have PHP logic of some sort in them. Mostly it's "make this link only if this other module is enabled" (which could be fixed if there was a better cross-linking mechanism), but there are a few that do more complicated things like making a list of all field-providing modules.
  • [admin list] The code in the Help module that displays module help pages also adds at the bottom a list of all of the administrative pages that are provided by the module. This can be helpful.

Proposed resolution

We need to come up with a new architecture and user interface for a Help system that includes as many of the above features and solves as many of the above problems as possible, without introducing new problems. Over the years, there have been many proposals to do this.

Here is the current proposed plan: Keep hook_help() in place, for "Module Overview" help topics. Add a new Help system that would co-exist, using config entities. Each module, theme, or profile can provide topics in config/install or config/optional, and site administrators can create more topics and organize them into a hierarchy. Topic authoring will be through a user interface, and exported as configuration, so non-programmers can easily write and contribute help. Topics will be broken up in configuration YAML into paragraph-sized chunks, for easy translating.

Other proposals

Here is a list of other proposals that have been discussed here or on other issues, but are not currently the main Plan of this issue:

Process and where to find it

This proposal was previously a core issue: #2351991: Add a config entity for a configurable, topic-based help system, but it was abandoned for Core around the initial Drupal 8.0 release, due to missed deadlines. It is available now as a Sandbox module: Configurable Help, which works fine, has automated tests, and has only a few outstanding issues (mostly feature requests).

This proposal has also been discussed and reviewed on this issue, mostly starting at comment #26 (including a quick usability review by yoroy). It was also demonstrated and discussed on 14 Nov 2017 at a Drupal Usability Group meeting, which was recorded on video.

This Sandbox module would be added to Core initially as an Experimental module -- issue for that: #2920309: Add experimental module for Help Topics.

Once that is done, one need would be for more Core topics to be written; the Sandbox only has a few right now. There is an issue in the Sandbox outlining which topics should be written: #2687107: Write some core help topics (this can be moved to Core as this initiative moves forward).

Another thing that would need to be done, probably after the initial Experimental commit, is to add a Search feature. Issue for that: #2664830: Add search capability

Proposal roadmap

Tasks to be done:

  1. Make a Core patch that adds the existing Sandbox module to Core as an Experimental module. Issue: #2920309: Add experimental module for Help Topics -- postponed until this initiative gets approval.
  2. Full usability review. This has been reviewed already by Yoroy on #30.
  3. Write some more Core help topics -- see issue #2687107: Write some core help topics on the current Sandbox module. This could be done after the module is in Core as a Beta Experimental module, before its full release
  4. Add a search feature. This could be done during the Beta phase, after initial Experimental module commit and before full release. Issue: #2664830: Add search capability
  5. Consider whether other features would be desirable, such as index or glossary.

Not in scope

Index and glossary are probably not in scope but could be added later.

Related work

Existing core features

a) hook_help() provides module overview topics and top-of-page help blocks. However, see the Problem section above for deficiencies in this system.
b) Tour module provides "tours" of how to use particular administrative user interface pages, which is useful. However, it doesn't tell an administrator how to accomplish a task if they don't already know which page to go to.

Open core issues

None known at this time.

Contributed projects

Sandbox module exists, by jhodgdon, who is attempting to get this in Core and resisting making it a full Contrib module. See above.

Team and resources

  • Initiative coordinator: jhodgdon and/or Amber Himes Matz
  • Making the initial Core patch: jhodgdon
  • Core module maintainer once it's in Core: Amber Himes Matz and/or andypost
  • Usability review: yoroy has done a quick review already
  • Writing more help topics: jhodgdon and Amber Himes Matz can write and/or coordinate volunteers (both coordinated User Guide project)
  • People who have said on this issue that they want to help: gnuget, vijaycs85, andypost, jhodgdon, Amber Himes Matz


Signoffs needed

Idea: Product manager: dries or webchick, yoroy, Gábor Hojtsy
Plan: Release manager: cilefen or xjm
Plan: Framework manager: effulgentsia, catch, alexpott, larowlan, platch

Also, consult these maintainers

Help subsystem maintainer: (none currently)
Documentation maintainer: (none currently)

Signoffs given

Idea: Product manager: signed off by yoroy in comment #66
Plan: Framework manager: signed off by larowlan in comment #64
Plan: Release manager -- (not yet)

#30 configurable-help-topics.png421.32 KByoroy
Members fund testing for the Drupal project. Drupal Association Learn more


jhodgdon created an issue. See original summary.

jhodgdon’s picture

Adding more issues to summary.

jhodgdon’s picture

Issue summary: View changes

OK, I think this Meta has been created with the existing proposals and issues related to major overhauls of Help system. I left out a few smaller feature requests, but I think all the major stuff is here.

batigolix’s picture

If the User Guide ( proves to be successful then it could replace the module help texts (2nd function of the hook_help as mentioned in description). We could then move all that text out of drupal core into asciidoc files in the User Guide contrib module. This idea is kind of related to the idea of replacing hook_help with advanced help (#402404: Use approach like D7 Advanced Help for the Help module).

jhodgdon’s picture

Added a new child issue to this: #2661200: Make admin/help page more flexible, and list tours on it which I'm actively working on for 8.1.x.

jhodgdon’s picture

That other issue I mentioned in the previous comment is probably/hopefully close to being done. I'm looking for final reviews so we can get it into 8.1.x. If you are interested in this issue, you probably want to look at #2661200: Make admin/help page more flexible, and list tours on it. Thanks!

meeli’s picture

Has there been much usability testing on the existing system? It would be good to do some tests, even if we know the results will be poor. This seems like a good set of feedback from developers who implement help, but I think it's important to address the feedback from users accessing help too.

Getting feedback from the people who actually want to use this module and read help documentation would be a good way to establish objectives for the re-architected system so you don't end up building something that has a whole other set of usability issues.

yoroy’s picture

@meeli this is from the last usability test: with this corresponding issue: #2516902: Introduce a visual hierarchy to the help page.

jhodgdon’s picture

Yes, the [non-topical] idea from the issue summary is basically the result of usability testing and/or the constant complaint that a user who doesn't already know how to do something would never be able to figure out anything from the current hook_help module overview system.

This is why we need a topic-based help system -- see #2351991: Add a config entity for a configurable, topic-based help system for one possible solution, and there are other child issues as well. I personally think the help entity system is the best option, and I was hoping to get it into 8.1 but it is not going to make the deadline, so for the moment it is just a "sandbox" module.

I am trying to get a part of this into core so at least I can promote my sandbox module for this to full Contrib but even that is not going too well and may not make the 8.1 deadline at the end of this month -- see #2661200: Make admin/help page more flexible, and list tours on it. Given that that may not even make the deadline at the end of the month, I think there is zero chance for the rest for 8.1. Maybe 8.2. Sigh.

Version: 8.1.x-dev » 8.2.x-dev

Drupal 8.1.0-beta1 was released on March 2, 2016, which means new developments and disruptive changes should now be targeted against the 8.2.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

ifrik’s picture

[must enable] Would it be possible to have the help texts in a yml file instead of in the module? Then it would be possible to already read the help page without the module being enabled. (Similar to the module description displayed on the modules/extend page that also comes from a yml file.) Then it would also sense to say more about dependencies on libraries or so in the help.

[module and/or topic based help]
I think it is good to have a module based help that explains the functionality of that module, because these texts can also explain words used or the specific action of a specific tick box somewhere. It also means leaves the responsibility to explain that module - but only that module - to the module maintainers.

A topic based goes crosses several modules, and maintaining it especially for contrib modules will be more complex. Just as an example: Geofield, Leaflet and Openlayers modules can all provide their individual help/explanation for the module, but in a topic based help they would all need to go together somehow - and each additional geo-related module would need to be include there somehow as well.

Maybe it would be useful to group the different module-help pages by topic/functionality (similar to the Configuration page).

And we could make use of the User Guide by adding a section on the module help page with links to the relevant pages in the User Guide. That way we would have the best of both without overburdening module maintainers.

jhodgdon’s picture

There are currently two proposals in consideration that might help with the [markup] part of this issue. Adding them as Related.

Regarding #13:

a) The idea of having help in a YAML file that could be loaded without the module being enabled... Currently in Core, most YAML files either supply plugin instances or configuration.

Examples of plugin instances are the modulename.links.admin.yml files that define admin menu links -- plugin YAML files are only read in when the module is loaded.

Examples of configuration are content types, field definitions, or views provided by a module; these are also only loaded when the module is enabled. My Configurable Help sandbox project is also using configuration entities.

One other type of YAML file we have is the info.yml file, which is loaded also when you go to the Modules page... so I guess we could in principle have help provided through something like that.

b) I agree that topic-based help is more complicated to set up and maintain. However, if the topics are small, they might only cross one module at a time or at most two.

And I'm not sure that a hierarchy of hook_help() topics would really help much if we were still limited to one topic per module. So for instance, if you had heard of cron and wanted to know what it is or how to set it up, how would you know where to look to learn more (which would currently be in the System module help page)?

So... I don't think we should give up the idea of having a module overview help topic page for each module. Module overviews are good. But I think in addition, if we had some more task-oriented and concept-oriented topics, organized with a sensible navigational structure, that would make the help way more helpful.

Cameron Tod’s picture

Do we want help to be contextual help, or do we want better in-app docs?

If its help, I would prefer something akin to tour module, which shows help in the context of the page.

If its docs, something like feels viable to me - a collection of structured articles in markdown/sphinx format that can be written or read in any text editor, but which can be easily parsed into useful, searchable, structured HTML. If you needed the per-path functionality of hook_help, you could have a file in the root of your module which mapped help doc files to paths, eg

doc: path/to/docs/
     route: routename
     doc: path/to/docs/
jhodgdon’s picture

See issue summary. We are talking about both contextual help and articles. The issue summary lays out the problems with the current system fairly well... Tours are not really the same as a small amount of context or background information to provide at the top of a page (which is what the hook_help() and help block are meant for). I think they are complementary.

Regarding readthedocs, we are working on a separate User Guide for Drupal 8 here, using a similar procedure and AsciiDoc (not Sphinx but it isn't very different):
There is definitely some overlap between "help topics provided within the Drupal site" (which should be concise and minimal) and "full detailed user guide with index, contents, etc." (which should go into more detail), but I think there is a place for both of them.

ifrik’s picture

Could we include a more systematic glossary into the help system?
Because we seem to write more and more documentation - and systems to provide help - without an actual basis of what which word means.

There are lots of attempts to give longer explanations of how to do things with Drupal, and the D8 User Guide will hopefully bring us a long way. But often we miss the basic explanation of what term actually means. This is certainly the case for site builders who are working with core and contrib modules. It seems to be easier to find videos and blog posts, then a straight forward explanation of what the difference is between "entity" and "entity bundle", the three different uses of "context" provided by three different modules, and why one groups module refers to "non-members" and the other to "outsiders"?
Different glossaries exist for example on d.o., in the User Guide, or in several books, but there is no systematic or sustainable approach to keep them updated. So we end up with users who have to search through longer documents to find a basic explanation, and with contrib developers who have no place for checking whether terms are already used.

I know this probably goes beyond this issue, but could we provide a more robust glossary through the modules?
Could each module contain a list of terms and their definitions, that can be displayed as a glossary on a site, similar to the help page?

Then site builders and administrators would have the terms they need at hand, making Drupal easier to understand.
It would make module maintainers responsible for defining the words they use, instead of leaving it as an afterthought.

jhodgdon’s picture

It would be possible to devise a system. Maybe file an issue in help.module, add add this idea to the issue summary?

ifrik’s picture

jhodgdon’s picture

Issue summary: View changes

Oops, you mean: #2701289: Glossary to extend the Help system -- I'll take a look. Also added to the issue summary here.

Version: 8.2.x-dev » 8.3.x-dev

Drupal 8.2.0-beta1 was released on August 3, 2016, which means new developments and disruptive changes should now be targeted against the 8.3.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

dawehner’s picture

After some talking with @alexpott this morning, here is an alternative approach, which could be both flexible but also nice to work with: #2820166: Flexible plugin based help system
Unlike before we are combining the power of plugins with the niceness of twig templates, while still be able to keep the existing hooks in a BC layer.
Any feedback would be great!

xjm’s picture

Project: Drupal core » Drupal core ideas
Version: 8.3.x-dev »
Component: help.module » Idea

This sounds like a good candidate for the Drupal core ideas queue.

yoroy’s picture

There's already so much detail in the issue summary that I can't really see the general goal. From the "reasons to make changes" list, which are the main goals, improvements we want to aim for?

(For me it would be moving from per module to a goal/task related topical grouping)

jhodgdon’s picture

If I had to order the "reasons to make changes" in priority order, here is what I would say:

[non-topical] & [limited list] (make it goal/topic oriented, with unlimited number of topics -- however, I don't think we want to lose the ability for each module to have a designated Module Overview help topic that we have now -- they are still useful)

[cross-links] (make an easy way to show that topics are "related", which could be a hierarchical structure with a "related" field as well)

[no admin] (make a way for a site builder to add pages to the help)

[authoring] (make it easier for non-programmers to contribute documentation to Core)

[no-search] (make a way to search help)

[glossary] (have a glossary of terms)

[must enable] (you need to enable a particular module to see its help)

These are more technical/implementation and less about general goals:

[code] (it's currently a hook instead of being d8-ish)

[many strings] (make sure it continues to be localizable as strings that are no longer than a paragraph)

[admin list] (don't lose the list of admin pages provided by each module, which is currently displayed on hook_help pages)

jhodgdon’s picture

As a note... I have this contrib/sandbox module "Configurable Help", that satisfies many of these goals (not coincidentally):
It mostly works, has tests, etc. There are 5 open issues, one of which is a small bug that could be fixed if anyone cared to fix it, and the rest are enhancements.

This module allows module/theme/distribution developers and site builders to use a UI to create config entities, each of which is a help topic. For modules/themes, they then can export and save in config/install or config/optional (the topics can have dependencies on other modules/themes, in which case they go in optional). Translation would be via config translation -- the topics are written in paragraph-style chunks (which can be list items, headings, paragraphs, etc.). So each paragraph-sized chunk is translatable. Site builders can edit existing topics in the UI as well, the same way as you can edit system-provided views.

Topics are displayed in their own section of the admin/help page. Core currently has the Module Overviews section (hook_help()) and the Available Tours sections on admin/help. This module adds a new Topics section, which is hierarchical. Topics also have a related topics field (so that if you are looking at topic A, you will see links to anything topic A has listed as Related, or topic B that lists A as Related). The sandbox has a few topics written for various Core tasks. One of the open issues is "write more topics", but you can at least install it now and take a look if you want.

When I originally proposed this for Core, one of the objections people made was that it should be Content not Config. I disagree -- config already has a mechanism for sharing/exporting/including with a module, as well as translating on Creating such a mechanism for a Content entity would be, I think, a waste of effort. And other than that, I don't really remember what made it not get into Core. Maybe it just wasn't ready and missed a deadline, back when 8.0 was the deadline for new features.

Oh, another objection was that people said admins shouldn't be able to edit the help. But on this, I also disagree, as from a site builder perspective, being able to define your own help system, and maybe hide/show/rearrange pages, is very useful.

Anyway... maybe it is time to revive it?

gnuget’s picture


Thanks for all your work on this.

I just created: with a small fix.

jhodgdon’s picture

Thanks to your patch on that other issue, all of the tests for the config_help sandbox module now pass against Drupal Core 8.3.x (and I think 8.4.x is pretty much the same still, so should be OK there too).

The next step if we wanted to proceed with this project getting into Core would probably be to turn it into a Core experimental module. And someone would need to volunteer to maintain it in Core. I personally am not willing at this time to commit to being a Core maintainer of anything, but would be happy to provide behind-the-scenes advice.

Prerequisites to making this a Core module:
a) There is one bug in the sandbox module that would need to be fixed:
#2744301: Saving with a changed ID generates an error

b) And probably we need some more help topics. There's an issue:
#2687107: Write some core help topics

I'd be happy to help with either of these... especially the second. But I'm not sure whether there is any interest from the Core maintainers at getting this module into Core, or if they still have major objections to it.

gnuget’s picture

Who do we need to ask to know if there Is interest to promote this module as replacement to Hook_help?

I think Hook_help is something that we really need to improve or replace with something better.

yoroy’s picture

Component: Idea » Proposed Plan
421.32 KB

Did a quick test drive of the sandbox module. It's really nice:

Help topics overview

Only local images are allowed.

The module adds a section to the help page that lists the help topics.

Help topics admin list

Only local images are allowed.

In the admin there's a list of topics. You can add/edit new topics or unlock the ones that are provided by modules:

Only local images are allowed.

Edit a help topic

Only local images are allowed.

Here I added the existing "Getting started" instructions as a help topic. Looks like the content creation interface brings its own "help HTML" text formats and it has a "simple paragraphs" (?) approach to create structured content. For which there very likely are very good reasons (maybe even spelled out in this issue!) but first impression was that it felt awkward.


Thanks @jhodgdon, I hadn't taken the time to actually look at the thing before, but I really like it and think it would be a welcome improvement for Drupal 8. This probably needs some more fleshing out in terms of where to start and what the MVP should be. Moving this from "idea" to "proposed plan". Most importantly it would need a team of people willing to work on this.

@gnuget so yes, you're very welcome to help move this forward :)

gnuget’s picture

Here I added the existing "Getting started" instructions as a help topic. Looks like the content creation interface brings its own "help HTML" text formats and it has a "simple paragraphs" (?) approach to create structured content. For which there very likely are very good reasons (maybe even spelled out in this issue!) but first impression was that it felt awkward.

The main reason to set this as "paragraphs" is (see to keep the translations separated if one typo is fixed only that paragraph should be marked as "outdated" and not the whole page.

I'm willing to work on this to help make this happen.

- David.

yoroy’s picture

I did a quick demo of this during yesterday's UX meeting:

jhodgdon’s picture

I'm so happy this is getting revived!!!

I'm traveling and without a computer for the next two weeks... I can get email and have web access but no computer for programming. (Good to take a break now and then...). So, I won't be able to help at the moment, but will occasionally get email and you can make issues in the Configurable Help project if you have suggstions for improvements.

One small note: I do not think we should eliminate or replace hook_help(), I think now that it is labeled as "module overviews" on the Help page, it make sense to keep it. This new help system, if we adopt it, is more for topics/tutorials, and I think we can have both, with different purposes.

jhodgdon’s picture

Is there still any interest in moving the Configurable Help forward into being a Core module? Because if not, someone's asking for it to be released as a full contrib module on #2901802: Release as module, please..

My preference would be to get it into Core, but it needs someone to volunteer to be its maintainer (I am done being a Core subsystem maintainer, sorry). Plus possibly some work.

vijaycs85’s picture

@jhodgdon I would love to get this part of core. not sure how much time I can spend getting it in though.

jhodgdon’s picture

Well, I can spend some time on patches, etc. The module works as it is (in the sandbox), and getting it into Core should not be that difficult. The easiest thing would be to just add it into core/modules... though some parts of it might be better off under core/lib, and some of the topics that the module provides could be better off under other modules.

Things that would most likely have to be done before getting this into Core:

a) Port the functional tests. They are current using simpletest base classes and that is deprecated. They need to be PHPUnit tests instead.

b) Write some more topics, but if it goes into Core as an Experimental module, that could probably come later, and maybe having it there would induce people to want to help write topics.

c) It needs to have someone volunteer to be its subsystem maintainer (to go in MAINTAINERS.txt).

jhodgdon’s picture

Oh, and probably (d): Convince one of the 8.x branch maintainers to let it become a Core module.

jhodgdon’s picture

Issue summary: View changes

The Proposed Resolution in this issue includes many possibilities. I moved the one we've lately been discussing to the top of the list and added a note that it is being discussed, because I'm also adding it to #2905741: *DRAFT* Proposed product goals for Drupal 8.5/8.6(+) core and I wanted this issue to be less confusing if someone came to look at it.

jhodgdon’s picture

Issue summary: View changes

@yoroy marked this as Proposed Plan on comment #30 about 6 months ago. Under the process that is somewhat described on
I think the next step if we actually want this to happen is to get it to be an Approved Plan.

To do that, we need to have a plan document. The template is here:

So, I am rearranging the issue summary here according to that template.

jhodgdon’s picture

Issue summary: View changes

OK, I think that summary is pretty much there.

The main hole is in the Team section: I think that before this will be moved to Accepted Plan, we need to have:

- Initiative coordinator -- maybe I can do this, but I'm not always around so maybe someone else would be better. I would be willing to coordinate an effort to write some more help topics... that is probably mostly what is needed... I do have some experience with that recently (User Guide project).

- Core maintainer -- once this is put into Core, someone needs to volunteer to be its Maintainer. I am NOT volunteering for that. I've been a Core maintainer before and I lack the time/energy to do it at this time in my life. Sorry. I think we need to find a volunteer for this now.

- More people interested in helping in general probably. Issues will come up, and we will need some coders to help resolve them. So far, I'm the main person who has worked on this effort, along with a few people who reviewed the initial core patches back a few years ago.

Amber Himes Matz’s picture

Hi @jhodgdon, I've downloaded the sandbox module and am reading through the code. This is the first time I'm seeing this issue, but I'm very interested in helping out. I'd like to throw my hat in the ring to be the core maintainer, something I think I could do with some guidance/mentoring. I'm willing to learn the process and set aside time/energy for it.

jhodgdon’s picture

Issue summary: View changes

That's exciting! I would be happy to help and/or mentor behind the scenes (subject to being around, which I'm not all the time, hence why I don't have time in my life right now to be a Core maintainer). And as I already put in the issue summary, I can also make the initial "get it into Core as Experimental" patch (which is basically the current sandbox, put into core/modules, with a very few small changes if any).

I'll add you to the summary... Also you might want to read
if you haven't already (this would be a module, which is a considered to be a subsystem of Core).

pasan.gamage’s picture

Hi jhodgdon,

Happy to contribute my time for this.


jhodgdon’s picture

Issue summary: View changes

Great, thanks! I'll add you to the list in the issue summary.

jhodgdon’s picture

Issue summary: View changes

@Amber Himes Matz -- So, should we try to get the signoff ("official blessing") now? One of us should probably be the Initiative Coordinator -- any thoughts on the team or the plan that are in the issue summary before we ask for signoff from the Release and Product managers? If more team members step up here we can add them later, but I think we probably have enough to get started at least, given that there is already a working prototype...

jhodgdon’s picture

It is probably slightly premature, but I went ahead and created a Core issue and uploaded a patch that takes the sandbox and adds it to Core as an experimental module.
#2920309: Add experimental module for Help Topics

andypost’s picture

@jhodgdon I'm in) Going to dig the code but can maintain the module in core

jhodgdon’s picture

Issue summary: View changes

Adding new issue link to summary, a few small edits, and adding andypost to the team, thanks!

jhodgdon’s picture

Anyone looking at the code -- you might want to take a look at the issue summary on #2920309: Add experimental module for Help Topics, which summarizes the features, API additions, UI additions... at least it's a bit of a roadmap. And probably ask questions about the code there rather than on this issue, since this is Ideas and that is Core. Thanks!

jhodgdon’s picture

OK, it looks like the next step is to add tags to this issue asking for the Product and Release managers to approve the plan. Since there are no maintainers for Help or Documentation currently, I guess this is all the signoff we can ask for.

Also small updates in Team section of summary.

Amber Himes Matz’s picture

Issue summary: View changes

@jhodgdon Yes, let's proceed.

Regarding who should be the Initiative Coordinator, certainly you have carried the torch with regard to vision and getting the project to this point, so this role is yours if you want it, but you mentioned availability constraints, so I am willing to be put down as this, too. I'm confident we can communicate here or in backchannels to ensure that I'm up-to-date on the project and understand the scope and vision.

Issue summary, team, and plan all look great. As you mentioned, we can add more team members as we go along. I daresay between us, we will be diligent about adding documentation for the module, so I'm not concerned about the lack of docs lead right now.

Do you have a core patch ready that adds the existing Sandbox module to Core as an Experimental module? I think that's the next step.

Amber Himes Matz’s picture

Ha, looks like I took too long writing my comment. Thanks @jhodgdon for moving forward with creating the core patch!

jhodgdon’s picture

Status: Active » Needs review

I have us down as core-initiative-leads, so that should be fine. :)

Amber Himes Matz’s picture

Sounds good. Thank you.

jhodgdon’s picture

Anyone who was hoping to help with this initiative but hasn't figured out how... I just posted #2920309-38: Add experimental module for Help Topics with some suggestions, for both coders and non-coders.

webchick’s picture

Exciting to see this initiative picking up steam again!

To provide product manager sign off, we need an opportunity to see what you have in action. As mentioned over in #2920309-39: Add experimental module for Help Topics, the most straight-forward way to do that is probably to attend a UX meeting and demo the patch. Let us know when you'd like to attend!

jhodgdon’s picture

Thanks for taking a look! As per your comment on the other issue, also adding the framework tag here, and I'll see about doing a demo.

jhodgdon’s picture

Issue summary: View changes

Updating signoffs section in Summary, to add framework maintainer and update who is eligible to sign off since more people have been added recently. :)

jhodgdon’s picture

Issue summary: View changes

Adding a link to the YouTube video from the Usability meeting a couple of days ago where I demoed this project-in-progress and got some great feedback from the usability team.

jhodgdon’s picture

So... This Proposed Plan has had a stable issue summary, and has been marked Needs Review, with tags asking for feedback from Product and Release managers, since November 1. The only feedback I have gotten was from webchick saying we needed to add Framework to the reviewers (which was done on 9 Nov) and asking for a demo of the current work in progress (which was done on 16 November at the UX meeting).

So there are two things going on here. On *this issue*, we are proposing a Plan that is intentionally a bit vague on implementation details, but has specifics of the features we want to have. On a separate issue, we are working on the implementation (which is premature since we don't have official approval for the Plan yet... but so it goes, we are coders and we like to work on code :) ).

So can we get this Plan approved as an Official Initiative, or can we get some feedback and make changes so that it is an approved Plan? The Signoffs Needed section says we need sign-off from the following to make this an Initiative:

Release manager: cilefen or xjm
Product manager: dries or webchick, yoroy, Gábor Hojtsy
Framework manager: effulgentsia, catch, alexpott, larowlan, platch

Can reps from each of these three groups please either sign off here, or provide feedback so we can revise the plan appropriately? Thanks!!

larowlan’s picture

I'm in favour of this as an idea.

I reviewed the patch on November 17th but did not post my review, as I didn't want to give any false hope before this issue was approved.

If this were to be an approved plan, I'd be happy to work to help shape the patch.

My only concerns with the current state of the patch were in relation to the section concept, where we were creating a new concept. This is similar to the concerns @xjm posted on the patch issue.

I don't think those concerns are insurmountable.

jhodgdon’s picture

Thanks @larowlan. Does that count as an official signoff from the Framework manager on the Idea (which doesn't specify the "text sections" idea anyway) (and I'm not asking at this time for a signoff on the patch, of course!)? I'm just trying to follow the process for initiatives and experimental modules, and it's very frustrating ...

webchick’s picture

Normally what we look for in this queue, like in any other queue, is an issue to get to RTBC, which means that there's been a peer review process + community members have looked it over and deemed the idea solid and worthy of sign-off by a maintainer. So I didn't realize you were blocked on us; I thought this was still in discussion.

larowlan’s picture

I am in support of the Quick summary of desired features from the issue summary. They are all admirable goals and certainly highlight the current short comings. One thing I would add is a desire that if all of this were to get in, ideally we could deprecate hook_help for Drupal 9 in favour of this approach.

So I think that counts as sign-off for this plan.

Correct me if I'm not doing this right..still finding my feet.

yoroy’s picture

Issue summary: View changes
Issue tags: -Needs product manager review
yoroy’s picture

I signed off on the idea as well. I think signoff from framework and release managers is mostly needed for the actual implementation plan, but @larowlan wants to see this feature happen too, all the better :)


jhodgdon’s picture

Issue summary: View changes
Status: Needs review » Reviewed & tested by the community

OK. I think we had quite a bit of community support in the previous comments, didn't set the status to RTBC, sorry! I was just trying to follow the procedures I found, and thought "Needs review" plus the "Needs ____ review" tags was the right thing to do... Anyway, I'll set the status to RTBC and I updated the summary for the two signoffs we have (yoroy had already updated with one but omitted the comment number).

webchick’s picture

Thanks! We've tentatively queued this for review on the product management meeting next Thursday.

jhodgdon’s picture

Wonderful, thanks!

Amber Himes Matz’s picture

Yay, I'm so glad to see this moving forward!

webchick’s picture

Status: Reviewed & tested by the community » Needs review

Gábor, @yoroy, and I looked over the plan on today's product management meeting.

A couple of things:

1) Searching help is currently listed as "Lower-priority but still desirable features." Yet, if you look at any modern help system, normally it leads with search, even moreso than a topic listing (see for example, Chrome). It feels like that ought to move to a "must-have" list rather than a "nice-to-have" list (for stable release, not initial commit).

2) During the UX review, @yoroy flagged the authoring UI as a no-go since it was popping up a new WYSIWYG editor per block-level element. We discovered during the call that you have been hard at work on this at #2926651: Better UI needed for entering body text, but haven't been able to see that in action yet to give sign-off. Overall, though, looks very promising! Thank you SO much for tackling this head-on!

3) As part of that issue, it probably makes sense for a more frameworky/subsystem maintainery person to take a look at the "chunking" approach. If it passes the sniff test, this could potentially be a really good way to solve what will end up being the same problem in the OOTB initiative with sample content.

Marking "needs review" in lieu of that sign-off, but keep up the great work!

jhodgdon’s picture

Issue summary: View changes

Thanks for the comments!

1) I'm OK with making Search be a "required for full module status" feature; I'm glad that you agree we can make the initial Experimental Module commit without Search and work on it after that. So... Changing the wording of the Plan so that it says Search is essential for it being a full module.

2) The authoring UI -- that is, issue:
#2926651: Better UI needed for entering body text
has both screenshots and a patch, if anyone would like to review it. With the patch, the UI for authoring looks just like the UI for Content entities with long text-and-format fields, so I think it will be fine from a usability perspective.

Sigh. I see that doesn't allow adding Configurable Help as an "additional project". I guess they don't support Sandbox modules. So, I'll try to make a Core patch on that issue in the next day or so that can be used for testing. I'll report back here when that's ready.

3) I'd be happy to have a code review of the chunking part of that patch too!

andypost’s picture

Related issue #1885192: Field locales_source.source is not suitable for long texts and huge config objects explains why help texts should be "chunked", I faced with it on #2836206: Translation of big webforms broken

Some work in this area happened in ctools #2844054: Inline Revisionable Content Blocks but it will hit the same limit of string translation

jhodgdon’s picture

Issue summary: View changes

Luckily, the current patch [which still needs review!] on #2926651: Better UI needed for entering body text both updates the UI so it looks like Nodes, and retains the chunking behind the scenes. :)

I will add those related issues to the other issue and to the summary of both this one and the patch issue.

jhodgdon’s picture

I made a Core patch out of #2926651: Better UI needed for entering body text.

So you should be able to spin up, and add this patch to Drupal 8.5.x, if you want to try out the new UI:

jhodgdon’s picture

On #2920309-79: Add experimental module for Help Topics, @dawehner has brought up some good points about two different possible approaches to getting a better Help system into Core.

The two approaches are, in short:
a) Help topics are configuration entities, created in a UI for managing/editing, which is issue #2920309: Add experimental module for Help Topics
b) Help topics are plugins, created with entries in YAML file and Twig templates, which is issue #2820166: Flexible plugin based help system

In this comment, I am reproducing @dawehner's comment from the other issue:

(item 5 from comment 79)
As a site owner I disliked having to add migrations, so it is confusing for me to deal with help configuration entities.

(end of comment 79)

For myself I tried to compare the approach of using config entities to the one outlined in #2820166: Flexible plugin based help system a while ago.

The main new features this adds are:
- Ability for modules, themes, and distributions to distribute arbitrary numbers of help topics (instead of just one and just for modules). This allows topics to be task-based and user-centered rather than organized by module.

N things of a kind is a central part of plugins.

- Because help topics are config entities, they can have dependencies (such as one of module A's help topics depending on also having module B installed).

Plugins can have some sort of simple dependencies. Migrate has some special code to add more complex ones, so plugins would fullfill this featureset.

- The help topics can be arranged hierarchically and have cross-links: topics can have a parent topic, plus a list of "related topics", and topic X can also say "I'm related to topic Y" so that if topic Y exists, X will be listed as related on that topic (allowing contrib topics to list themselves on core topics, for example).

All this information could be put into the twig file/plugin information.

- The admin/help page lists top-level topics only (for less clutter).

That would be enabled by filtering the plugin definitions.

- Administrators can edit topics and create their own (to make a help system specific to their site).

Editing existing ones is not directly supported, but we have experience with exposing twig in userinterfaces (views), so we could do that. I'm honestly a bit confused why adding custom documentation to a website is something most sites using Drupal need. This is obviously something to be thought about by the product team.
On the other hand the plugin system provides you the flexibility to add this feature in. Just like migrate in contrib allows you to add additional migrations (i think by using config entities), such a help UI module could leverage the same power of plugins. For me this situation feels really similar.

- Help topics bodies are HTML, with a text format, so they can be edited much like Node module content items.

- Each help topic is broken up into paragraph-sized chunks, and stored as translatable configuration (so they can be translated on by paragraph). See also #1885192: Field locales_source.source is not suitable for long texts and huge config objects -- this is not only desirable but necessary -- long topics definitely need to be broken up into smaller strings.

Using twig files and ```translate``` would allow us to also use the normal localization tools.

- No PHP knowledge is required to author help topics.

Nor is twig.

- The existing hook_help() system and Tour module are not replaced by this system, since they complement each other.

jhodgdon’s picture

I'm also adding here a comment from @Amber Himes Matz about why we need a revised help system, after @dawehner called that into question at the top of his review on the other issue:

A common best practice of documentation is to put the docs as near to the product as possible. In this case, the website being the product and the help system within the site being the documentation.

Commonly, an agency would create docs using a custom module and hook_help or previously Advanced Help module before handing off the site to the client. Further additions to the help documentation (after hand-off) would then rely on a developer or at least someone familiar enough with the code base and copy-pasting skills to add more help files for their site.

This solution provides a UI that both an agency and a client could utilize to create and maintain up-to-date documentation for their site. This is a much needed feature, especially due to a site's oftentimes unique or custom process of entering content on their site.

The audience here is a marketing person or content editor -- not only the developer. And not necessarily someone with access to the codebase to "just" create new Twig files.

The objective is to make site-specific documentation creation and maintenance possible for the site builder, administrator, or content manager, while also making it possible to export the configuration and move it to another instance of the site.

jhodgdon’s picture

So here are my thoughts about the two approaches listed in comment #76 above:

The advantages of the help topics as config entities approach on #2920309: Add experimental module for Help Topics are mainly that (a) it has a viable patch now and (b) it provides a UI.

The advantages of help topics as plugins on #2820166: Flexible plugin based help system would be (a) presumably smaller code base (since there is no UI to maintain), and (b) config entities have disadvantages as far as migration goes.

Anything I'm missing here? So I think we could go the plugin route, but let's decide SOON and get something done. Right now that second issue doesn't have a patch...

markcarver’s picture

It seems rather odd that there really isn't much discussion around using the existing theme system for these.

Of all the output I've seen from help, it always contains HTML.

HTML does not belong in PHP.

HTML does not belong in YAML.

HTML does, however, belong in Twig; an HTML templating engine (which supports our translation system).

Even if this were to move into some abstract help directory and using a closed twig templating system.... how is a theme like Drupal Bootstrap supposed to alter the markup to display topics appropriate using the existing framework supported markup/classes?

I'd really rather avoid circumventing the theme system on this one.

As it stands now, there is absolutely no [proper] way to hook into/style help output.

I really think this should just create plugins (automatically via YAML) and let the template name be extracted automatically based on the various criteria of the plugin definition.

Using a similar example from #2820166: Flexible plugin based help system:

  type: topic
  title: "Topic title"
  template: ... # Automatically determined, but can be explicitly overridden.

There should be a global template (theme hook) registered: help.

Then, when it comes time to render each help plugin, it's invoked using theme hook suggestions:
'#theme' => 'help__' . $plugin->getType() . '__' . $plugin->id(),

This would allow individual topics to be customized for their given hook:

By leveraging the existing theme system, help would finally give themes the ability to properly preprocess or override any help output. Not to mention the added benefits of using Twig itself (including the ability to use blocks and extend templates as needed).

jhodgdon’s picture

Just to be clear... My interest is in having a system where module, theme, distribution maintainers, as well as site builders, can make multiple help topics for display in the Drupal site. I think either of these approaches can work. I have some work invested in the approach on #2920309: Add experimental module for Help Topics, but if we want to go in the direction of #2820166: Flexible plugin based help system (in other words, if someone wants to make an actual patch, and the consensus is that it's a better approach), I will gladly support that approach too. I agree that both approaches can solve the problem. So, let's pick one and solve the problem, get *something* done and committed to Core, so that Amber and I can mount an effort to get some help topics written, which is my main goal.

Really, we just need to decide whether it's important to have a UI (which I think is the main advantage to the config entity approach), or it's more important to avoid config entities and their migration problems (which I think is the main advantage to the plugin approach).

And if we're going the plugin route, we need a patch for that other issue. Soon. :) And I will be there to review, test, and offer suggestions on features/properties we need in the plugin system in order to support the goals of this effort, if we choose to go that route.

Anyway... Thanks for bringing this up again!

jhodgdon’s picture

Thanks @markcarver -- so are you advocating #2820166: Flexible plugin based help system or an even different approach?

markcarver’s picture

Yes, I'm advocating for #2820166: Flexible plugin based help system, but with the added bit of using the existing theme system + theme hook suggestions for automatical template discovery (no need to specify it manually in the YAML file).

andypost’s picture

Actually "plugin-way" is in core, we have some default plugins - why there's no twig help plugin?

Configurable storage for help topics is blocker on way of getting rid of hook_help

I'm digging into #2937483: Defining a new type of section storage relies on magic strings and hidden assumptions

Core already have a storable "sections" so topical help module could use it as wrapper for topics

jhodgdon’s picture

Note: Berdir put a comment on the other issue that is relevant to the plugins vs. config entities debate:
#2920309-87: Add experimental module for Help Topics

jhodgdon’s picture

I guess another question I have about the plugins-plus-twig approach is whether we think that content should be edited/stored in Twig templates. Or in config entities for that matter.

Semantically, the help topics should be content entities, because they are content. But it's problematic to make them content entities because we don't have a good way to manage, distribute, and update content with modules, themes, and distributions.

I don't understand having an argument about whether HTML markup should be or shouldn't be in the body of the topics, unless you think we shouldn't really have markup in the body of nodes or content blocks or any of the other content entities. I mean, I do understand that themes cannot override markup that is part of a body, but for any content that is composed of prose (such as web pages and content blocks and help topics), we do need some way to write prose that has paragraphs, bullet lists, links, and other semantically-relevant HTML as part of the body.

By the way... In the earlier versions of my help topics module, I split up the body into individual paragraph-sized chunks, and it was really themeable at that level. Basically, the topic editor/writer would indicate the structure as a paragraph, then 3 bullet list items, then 3 numbered list items, etc., and these were put into a "sections" render element, which the theme could do whatever it wanted with. But the Usability folks nixed the idea of editing it that way -- too much of a paradigm shift. People writing prose just want to write it in an HTML editor. It may not be purely themeable, but as a practical matter, I think the theme has to give up the ability to get down to the inner parts of prose body areas.


markcarver’s picture

I guess another question I have about the plugins-plus-twig approach is whether we think that content should be edited/stored in Twig templates.

The "content" you're referring to is and has always been static, stored somewhere in a file.

Semantically, the help topics should be content entities, because they are content. But it's problematic to make them content entities because we don't have a good way to manage, distribute, and update content with modules, themes, and distributions.

Semantically, content entities are intended to be mutable. In the sense that it is done so by some external source. They are also intended to live in the DB, not provided by a file somewhere.

I don't understand having an argument about whether HTML markup should be or shouldn't be in the body of the topics, unless you think we shouldn't really have markup in the body of nodes or content blocks or any of the other content entities.

Again, this isn't mutable content, nor is it like the "body" field in nodes that have CKEditor. No one is going to be "editing" help topics from core/contrib from the site's UI... nor should they be able to.

Thus, the only place that makes sense to house said static HTML is inside a Twig template. Not PHP, not YAML. Besides, having it in Twig automtatically gives the ability for future expansion, i.e. "Oh crap, we forgot X"... "That's OK, we'll just send another variable that the Twig templates can use."

Usability folks nixed the idea of editing it that way -- too much of a paradigm shift.

Probably because you were still mixing where the "content" (YML) and where the "HTML" (PHP) lived, no?

People writing prose just want to write it in an HTML editor.

And they could do that all in a Twig template. Where the content + HTML is combined.

It may not be purely themeable, but as a practical matter, I think the theme has to give up the ability to get down to the inner parts of prose body areas.

I think this is a lot like saying "themes don't matter" and why major advancements to the theme system in core is still in shambles. Just because themes "haven't done X before" doesn't mean they shouldn't. It often means that they "can't" due to the limitations of core's theme system.

I mean seriously, what if I wanted to wrap parts of the help system with collapsible panels, or vertical tabs or modals? You're telling me that as a themer I have to just "suck it up"? Usability is all and well, but when it impacts the core value of the system, extensibility, we have a problem.

One of the points of the Twig initiative was to remove all HTML markup from PHP files. Yes, there are a few outlying rouge elements (e.g. #2638250: The label "Member for" on user profiles is hardcoded markup that is different from other user fields), but as you can see from that example, something even seemingly as innocuous as <h4 class="label"> can cause major issues when dealing with an external front-end framework like Bootstrap.

The point is that core, contrib, nor prose editors know exactly how or what will ultimately be displayed to the end user. That is the sole existance and primary purpose of themes.

If a prose (contrib) editor decides to stray from said "simple" markup and uses classes and markup from "core themes" like Bartik/Seven, etc. How is an external framework like Bootstrap supposed to counter that?

What is "practical" is to reuse existing systems (plugins/twig) instead of trying to reinvent the wheel here and circumvent the rendering process.

jhodgdon’s picture

I agree that having markup outside of Twig is bad in many ways. Really, I do not disagree with this.

But I still think that the *text* of the help topics (at least, the part inside each paragraph, bullet list, etc. -- the help text body), as well as the semantic markup saying what each chunk of text is (is it a paragraph, a bullet list item, etc.) is content. Ideally, it should be editable content, editable by site builders and module/theme maintainers (see also comment #77 above in this issue).

So... what I'm saying is that I don't think we want to put all of the *content* of help topics into Twig templates. Do you think that is a good idea to have content there, or do you disagree that help text (including its semantic markup, some way to say "this is a paragraph" and "this is a bullet list item") is content in the first place?

markcarver’s picture

I think #77 is/should be an entirely separate issue/goal.

It conflates site-specific help with core/contrib help.

I personally do not want to get issues in my contrib projects saying that their site documentation says X, only to find out it's because some "marketing person" (who may not understand how something actually works) decided to edit the documentation provided by my contrib project. This is a pandora's box if I ever saw one.

Site-specific help should only be supplemental in nature, not authoritative over components it doesn't author.

Thus, I think that there are two types of "help" here:

  1. core/contrib - Not "content" per se because it lives in files
  2. site-specific - Supplemental content entities that are stored in the DB

The reality though is that core does not currently ship with mechanisms that this endeavor would seem to need: (converts file-based "default content" into DB content) (content structure)

jhodgdon’s picture

I do not really think that the proposal in #2820166: Flexible plugin based help system will make help topics themeable, for practical purposes. The proposal there is to put the content and markup of each individual help topic in its own indidual Twig template. And whether the name of the template file is chosen via theme suggestions or is in the plugin YAML, it would mean that a theme wanting to override the markup for help topics in general would need to override every single one of these template files, because each one contains the content and markup for an individual topic. This isn't practical.

Besides which, having a system where themes can override the content of the topics is similar to what you were worried about in #88:

I personally do not want to get issues in my contrib projects saying that their site documentation says X, only to find out it's because some "marketing person" (who may not understand how something actually works) decided to edit the documentation provided by my contrib project. This is a pandora's box if I ever saw one.

Substitute "theme designer" for "marketing person" here. It seems like the same problem, given that many/most Drupal sites have their own theme (although not so many have their own admin theme, I will admit, and probably help topics are displayed using the admin theme).

So,,, It sounds like your ideal world would be a help system where the content of help topics (and this must somehow include some way of the topic author to indicate "this is a paragraph, followed by a bullet list, ...") is stored somewhere in an immutable (but translatable) file. Then the markup that is generated to display the topic on a help page is contained in one or a small number of Twig templates, so that the theme can override the markup without touching the content.

The two proposals we have right now each violate parts of this ideal world. #2820166: Flexible plugin based help system (as currently set out, anyway) puts the markup and content for a given topic into the same individual Twig template, effectively making the topics unthemeable for all practical purposes (would need to override all Twig templates for all topics), and making it so a theme can override the content of topics (so, not immutable). And #2920309: Add experimental module for Help Topics puts the content-plus-markup into config entities, making the topic body unthemable (although the topic page as a whole, including the Related section, has markup in a Twig template and so is themeable), and also making it so a user can override topic content in the admin UI (although there is a locking system so that topics distributed by modules/themes are locked to editing).