Problem/Motivation
The existing 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.
This system works OK, but there are several reasons for wanting to make changes in this system (each of these is given a code name for future reference):
- [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.
- [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.
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 localize.drupal.org has some "fuzzy" logic that would preserve the old translation somehow.
- [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
Think of a new architecture for help that solves some or all of these problems, but doesn't introduce too many new ones. Current issues and contrib projects with ideas:
- #402404: Use approach like D7 Advanced Help for the Help module -- Proposes to add essentially the Advanced Help module to Core. The idea is that modules provide help topics in HTML format, with a hierarchy file. Somewhat resolves issues [non topical], [authoring], [code], [cross-links]. Breaks desirable features [many strings], [php code], and [admin list] if this is a replacement for hook_help() rather than an additional help method.
- #2590319: replace hook_help with Help Plugin - Proposes to resolve [code] by replacing hook_help() with a help Plugin system. If developed fully, these plugins could be topics with titles instead of just module-level pages, which would resolve [non topical] as well. Doesn't kill desirable features.
- #1918856: Put each module's help into a separate Twig file - Proposes to resolve [markup] by putting the module topics into Twig templates. Might resolve [code] and [authoring] too. Could resolve [non topical] if modules, themes, and profiles could all provide topic files and if titles were somehow included in them. Breaks [php code], and if not done carefully, could break [many strings].
- #2351991: Add a config entity for a configurable, topic-based help system and sandbox Configurable Help module: Proposes to replace hook_help() with config entities (or add them alongside module overviews). Each module, theme, or profile can provide topics in config/install or config/optional, and admins can create more topics and organize them into a hierarchy. Resolves [non topical], [no admin], but breaks [many strings]. If hook_help goes away, it also resolves [code] and [authoring], but breaks [php code] and [admin list]. The module also resolves [limited list] currently, by making a way for modules like Tour to add sections to admin/help. This part could be put into other patches/ideas.
- #2188753: Get rid of hard-coded markup in hook_help() implementations - Proposes several ideas for resolving [markup] and [authoring]. Not to the point of a patch yet.
- #102254: Add an administrative search feature - Proposes adding a way to search help, as well as administrative page titles.
- #2205713: Adapt main Help page (admin/help) so that Available Tours block can be added - fixes [limited list] for Tour module.
Remaining tasks
Decide. Patch. Test.
User interface changes
Better help.
API changes
Probably a different API for providing help; possibly with the old one still supported for backwards compatibility, depending on when this is adopted.
Data model changes
No.