Note on issue credits
At the end of this summary is a list of people who helped make this patch. They have not all commented on this issue, because the module was developed in a sandbox project. Please credit them. Thanks!
Problem/Motivation
We have long needed a unified way for core and both core and contributed modules, themes, and profiles to add help topics to Drupal. The current core Help module only allows each module to define one "module overview" help topic using hook_help(). This patch adds the following help-related functionality:
- 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.
- Topics are distributed as plugins. Each topic is defined in a Twig file, which contains a few settings as meta-tags (topic title, "top-level", and "related", see below), as well as the text/HTML body of the topic.
- When topics are displayed, there is a list of "related topics" at the end, specified by the topics'"related" meta-tags. If topic A lists topic B as "related", then A is listed on B and B is listed on A.
- Another piece of meta-data is "top-level" (Boolean). The admin/help page lists top-level topics only (for less clutter); others are reached through links in topic text and/or the Related Topics section.
Note: This idea was previously discussed in the Ideas queue, on #2592487: [meta] Help system overhaul, but the plan has evolved here on this issue.
Complementary help systems
There are two existing help systems in Core that complement this proposed system, and will most likely remain in place:
- hook_help() -- this allows modules to (a) add help to the Help block for particular routes/pages on the site and (b) create one Module Overview topic, which appears in the existing "Module Overviews" section of the admin/help page.
- Tour module -- this allows additional contextual help to be added to any page on the site, in the form of a tour, which can have multiple steps, each one describing part of a page (such as different form elements in an administrative form). Contrib modules like Tour UI allow non-programmers to create tours, and they are stored in configuration like the Help Topics of this proposal. Defined tours are also listed in the "Available Tours" section of the admin/help page.
Proposed resolution
a) Add the Help Topics module to Core, initially as a separate Experimental alpha module (this issue), with the intention of moving it to be part of the existing core Help module before full release (see (b)).
b) #3027054: Help Topics module roadmap: the path to beta and stable
c) As a note, the Sandbox module where development was started for this project will probably be promoted to a contrib module, with some additional functionality around letting people define help topics for their site and storing them in config entities, and providing a UI that site builders can use to author this type of configurable help. But that is out of scope for this issue.
Remaining tasks (and how to help)
On this issue, the task is to get the patch approved for this to be an experimental module.
Testing notes: After applying this patch and installing the Help Topics (help_topics) module, you can go to
admin/help
and see the current (fairly small) list of top-level help topics (there's an issue about writing more: #2687107: Write more core help topics). Click on one, and you'll see related topics. Also, you can try out links within the text of some topics that will take you to related administrative pages, or to other help topics.
User interface changes
A new Experimental module providing plugin-based help topics is added, along with a few new help topics.
The only change to existing UIs is that this module adds a section to the admin/help page that lists the top-level topics.
API changes
No changes to existing APIs.
Defines a new plugin type (for the help topic), and a new way to discover plugins (via meta-data in Twig files).
Data model changes
No changes to existing data models.
People to credit on this patch
This patch was made by the following people, who contributed patches/tests/reviews on either
#2351991: Add a config entity for a configurable, topic-based help system
or on various Sandbox module issues at https://www.drupal.org/project/issues/2369943, or at Usability group meetings, or here on this issue:
alexpott
amateescu
Amber Himes Matz
andypost
benjifisher
Berdir
catch
ckrina
dawehner
Fabianx
Gábor Hojtsy
Greg Boggs
gnuget
jhedstrom
jhodgdon
jibran
larowlan
MariaDenysyuk
miro_dietiker
Mixologic
sandboxpl
SenthilMohith
tim.plunkett
tstoeckler
vijaycs85
webchick
webflo
yo30
yoroy