Latest update
After a UX review (see notes in comment #132, we've decided to strip out the UI (and config entities), and start out with shipping an API that discovers YAML-based help topic plugins from themes and modules. Modules and themes can provide help topics as YAML-file-based plugins in a project sub-directory called help_topics. Any file in a module or theme's help_topics directory with the suffix *.help_topic.yml (e.g. example_module/help_topics/clear_cache.help_topic.yml) will be discovered by the Help Topic module. Plugin-based help topics provided by modules and themes will automatically be updated when a module or theme is updated.
A patch is ready for review. (See latest comments.)
Problem/Motivation
In the Ideas queue, on #2592487: [meta] Help system overhaul, we are proposing adding the currently-sandbox Help Topics module to Core as an Experimental module.
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.
- 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).
- The help topics can have cross-links: topics can have 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).
- Topics can be marked as "top-level" or not. The admin/help page lists top-level topics only (for less clutter).
- Further hierarchy and navigation could be created using the regular Menu system within a Drupal site.
- Administrators can edit topics and create their own (to make a help system specific to their site).
- Help topic bodies are HTML, with a text format, so they can be edited much like Node module content items.
- Each help topic body is broken up into paragraph-sized chunks, and stored as translatable configuration (so they can be translated on localize.drupal.org 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.
- No PHP knowledge is required to author help topics.
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) Approve the Plan on #2592487: [meta] Help system overhaul so that this becomes an official Initiative. Note: There are alternative proposals, so we need to finalize that decision.
b) Add the Help Topics module to Core, initially as an Experimental alpha module (this issue). To do that, we need to resolve these issues and get them into the patch here:
- [DONE!] #2942643: Remove the Preview functionality
- [DONE!] #2943919: Make sure route tokens have cacheable metadata
- [DONE!] #2943923: Connect help topic view page to admin page
- [DONE!] #2961552: Refactor using a plugin system
c) 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):
- [DONE!] #2942644: Config export contains CR characters
- [DONE!] #2942645: Translation UI must not allow changing HTML structure
- [DONE!] #2943917: Don't use Entity::url(), as part of #2943919: Make sure route tokens have cacheable metadata
- [DONE!] #2943921: Move body set/get to a unit test
- [DONE!] #2943920: Use newer API for getting module info (also incorporating #2923918: Theme autocomplete is not ordered)
- #2664830: Add search capability
- [DONE!] #2943974: Work-around for route tokens in Help text format getting truncated after editing a help topic Note: the patch for this issue is really a work-around. The root case is core issue #2944173: CKEditor mangles tokens in URLs, due to bug in Xss::attributes(), and that has not been fixed yet. I've added this into section (e) just below.
d) To get this module to full release, we will additionally (probably?) need to do these tasks:
- #2687107: Write some core help topics
- #2951560: Add tokens for embed and link of help topics
- #2665784: Add a token for images and a way to manage images
- 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, Create and write the online docs page for this module: https://www.drupal.org/modules/help_topics , etc. (Is there a standard procedure for this?)
- Figure out how to have an Edit link on unlocked entity topic pages, but not on pages that are plugin topics.
- Make a page that lists all Help Topics on the current site (plugins and entities, both top-level and not top-level). Currently we only list entity topics on the admin page, and only top-level topics on admin/help.
- 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:
- #2927346: CKeditor buttons for DL lists
- #2960220: Facilitate hierarchy and ordering of help topics
- #2951565: Expand permissions for help topics
- #2944173: CKEditor mangles tokens in URLs, due to bug in Xss::attributes() -- we have a work-around in place, see section (c) above and issue #2943974: Work-around for route tokens in Help text format getting truncated after editing a help topic
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). We are simultaneously updating the sandbox project so that it stays in sync with the patch here. So, you can review/test either the code in the patch here, or the code in the sandbox repository.
For this issue to be completed, the tasks are:
(0) Prerequisite: Agree on whether this is the best approach -- see #2592487: [meta] Help system overhaul
(a) Module tested, including usability testing. Usability demos resulted in a number of issues being fixed. See Proposed Resolution section above for remaining issues that need to be resolved.
(b) Code in patch reviewed. No known issues at this time, but the code needs a final review.
(c) [Done] Choose name for module -- See
#2921120: Change name of the module
The name "Help Topics" chosen on that issue has been incorporated into the patch here.
(d) Patch finalized with feedback from above items
(patch is being kept updated on each commit to the Sandbox repository, so all Fixed issues are reflected in this patch)
(d) Patch committed
We are using individual issues in the sandbox project to track what needs to be done to improve the code and module. Issue list:
https://www.drupal.org/project/issues/2369943
If you review the code or test out the module, please file issues in the sandbox project if you find things that can be improved. Or you can comment here and someone else can turn them into issues.
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. The other thing to test is the UI for editing and creating new help topics:
admin/config/development/help
User interface changes
A new Experimental module providing configurable help topics is added, along with a few new help topics. It has an administrative UI for authoring and translating 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, and a section to admin/config to reach the admin UI for authoring help.
API changes
No changes to existing APIs.
Defines a new config entity type (for the help topic).
Data model changes
No changes to existing data models.
The new help topic config entity defines a new schema for saving the help topics to config YAML.
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
gnuget
jhedstrom
jhodgdon
jibran
larowlan
MariaDenysyuk
miro_dietiker
Mixologic
sandboxpl
SenthilMohith
tim.plunkett
tstoeckler
vijaycs85
webchick
webflo
yo30
yoroy
