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
In the Ideas queue, on #2592487: [meta] Help system overhaul, we proposed adding the currently-sandbox Help Topics module to Core as an Experimental module. Since that Ideas queue issue, our plan has evolved here on this issue. Our current patch adds the following 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 goes in its own YAML file, which contains the title of the topic and a few settings. The body goes in a corresponding Twig file.
- When topics are displayed, there is a list of "related topics" at the end. These links are generated from two sources. When displaying topic X, topic X's YAML can specify zero or more topics to include in the list. Also, topic Y can say in its YAML file that it wants to be listed in topic X's Related Topics section.
- Topics can be marked as "top-level" or not. The admin/help page lists top-level topics only (for less clutter); others are reached through links in text and the Related Topics section.
Complementary help systems
There are two existing help systems in Core that complement this proposed system, and will 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). [Alternatively, it may be added as part of the existing core Help module to start. The product managers need to decide this.]
b) Once this is in Core as an alpha experimental module, we'll open a Meta issue to get this to Beta quality (which will be necessary to keep it as a live Experimental module in a full Drupal release). Sub-issues that we currently have for that phase (which are currently filed against the Sandbox module, but will be moved to Core once we have the module in there and an issue component):
- #2664830: Add search capability
- Better test coverage: more unit tests, tests for the cache stuff, tests for translatability
- Enforcement of provider.string format for plugin IDs (in patch)
- Addition of ability to scan core for plugins (besides themes and modules) (in patch)
- Make sure that the topic title/label gets into localize.drupal.org as a translatable string.
- Make sure topic Twig files are being scanned by POTX so the topic text gets onto localize.drupal.org
c) To get this module to full release, we will additionally (probably?) need to do these tasks:
- Make it part of the existing core Help module instead of its own module. This will mean (besides moving the files around):
-- merging the hook_help() here into the existing hook_help()
-- adding to the drupal.org docs page for the existing Help module
-- changing namespaces of classes
-- changing function names of hook implementations
-- moving topics to their rightful places (provider directories instead of all inside the help module)
-- [TBD]
- #2687107: Write some core help topics
- #2994748: Make a way for Help Page Sections to be ordered
- The standard things done in Core to finalize a module, such as adding templates to the Stable/Classy themes, updating the module category in the .info.yml file, removing @internal tags, adding @api tags, etc., (Is there a standard procedure for this?)
- Figure out POTX (getting the translatable strings into localize.drupal.org). See:
https://cgit.drupalcode.org/potx/tree/yaml_translation_patterns.yml
It looks like we would need to add to that file so that within help topic YAML files, we would define which keys are translatable.
e) And there are a couple of issues that we may or may not eventually need to resolve:
- #2960220: Facilitate hierarchy and ordering of help topics
f) 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 (see Proposed Resolution for list of issues to be resolved).
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 some 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).
Data model changes
No changes to existing data models. There is an implicit YAML schema for the plugins.
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