>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #2592487. --> Reported by: [jhodgdon](https://www.drupal.org/user/155601) >>> <h2>Background</h2> <p>Amber gave a presentation about this issue at DrupalCon Nashville (April 2018), which you can watch here:<br> <a href="https://events.drupal.org/nashville2018/sessions/new-help-system-drupal">A New Help System for Drupal</a>.</p> <p>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.</p> <p>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:</p> <p>- an officially-sanctioned way for Contrib maintainers to provide better help with their modules, themes, and distributions<br> - for Core to provide better help for itself<br> - for site owners to provide help to their internal team on how to accomplish their unique site-specific tasks</p> <p>Integrating better -- that is, single task/concept-based documentation -- with Drupal's existing help system rather than hoping that people adopt a system provided by a contrib module.</p> <p>Why should site owners be included here? Because site's own their configuration, they should also own the help that describes how to use that custom configuration. (See also <a href="https://www.drupal.org/project/ideas/issues/2592487#comment-12524622">comment #114</a>.)</p> <h2>Problem</h2> <p>The current Help system in Drupal 8 hasn't changed much since Drupal 4.6. How it currently works:</p> <p>a) Modules can implement hook_help().</p> <p>b) There are two different things you can do with hook_help():<br> - (1) Provide page-level help for an admin page, which is displayed in the Help block when that page is active.<br> - (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.</p> <p>There are several key features that the current system lacks that keep it from being a very useful help system.</p> <h3>Quick summary of desired features</h3> <h4>Features that would make the help system more usable</h4> <p>a) Help should be oriented towards goals/tasks (things the user would want to do), not organized by module.<br> b) There should not be limitations on how many topics a module provides (and themes/distributions should be able to provide them too).<br> c) There should be a way to have cross-links or "related" links between topics.<br> 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.<br> e) It should be easier for a non-coder to contribute help topics (currently they have to edit PHP to do so).<br> f) Help should be searchable.</p> <h4>Lower-priority but still desirable features</h4> <p>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.</p> <h4>Development concerns</h4> <p>h) The old help system uses a hook instead of a more Drupal-8-like plugin system.<br> i) We need to make sure the help text is localizable using our current systems like localize.drupal.org -- therefore its text should be broken up into translatable strings no longer than a paragraph. See also <span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-8"><a href="https://www.drupal.org/project/drupal/issues/1885192" title="Status: Needs review">#1885192: Fields locales_source.source and locales_target.translation is not suitable for long texts and huge config objects</a></span> -- this is not only desirable but necessary -- long topics definitely need to be broken up into smaller strings.</p> <h3>A more detailed list of desired features</h3> <p>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.</p> <ul> <li>[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: <span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-3"><a href="https://www.drupal.org/project/drupal/issues/2516902" title="Status: Closed (duplicate)">#2516902: Introduce a visual hierarchy to the help page.</a></span></li> <li>[no search] There is no way to search help.</li> <li>[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: <span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-3"><a href="https://www.drupal.org/project/drupal/issues/2188753" title="Status: Closed (duplicate)">#2188753: Get rid of hard-coded markup in hook_help() implementations</a></span></li> <li>[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 <span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-3"><a href="https://www.drupal.org/project/drupal/issues/2188753" title="Status: Closed (duplicate)">#2188753: Get rid of hard-coded markup in hook_help() implementations</a></span>.</li> <li>[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.</li> <li> [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.</li> <li>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. <del>[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. </del></li> <li>[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: <span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-17"><a href="https://www.drupal.org/project/drupal/issues/2587469" title="Status: Closed (outdated)">#2587469: allow hook_help to run on modules which are not enabled</a></span>.</li> <li>[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.</li> <li>[glossary] It might be useful to have a glossary of terminology that modules/themes could add entries to. This is a separate issue: <span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-1"><a href="https://www.drupal.org/project/drupal/issues/2701289" title="Status: Active">#2701289: Glossary to extend the Help system</a></span> </li></ul> <p>On the other hand, there are some desirable aspects of this system that we may not want to lose:</p> <ul> <li>[many strings] As discussed on <span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-3"><a href="https://www.drupal.org/project/drupal/issues/1918856" title="Status: Closed (duplicate)">#1918856: Put each module's help into a separate Twig file</a></span>, 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. See also <span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-8"><a href="https://www.drupal.org/project/drupal/issues/1885192" title="Status: Needs review">#1885192: Fields locales_source.source and locales_target.translation is not suitable for long texts and huge config objects</a></span> -- this is not only desirable but necessary -- long topics definitely need to be broken up into smaller strings.</li> <li>[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.</li> <li>[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.</li> </ul> <h2 id="summary-proposed-resolution">Proposed resolution</h2> <p>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.</p> <p>Here is the current proposed plan: </p> <ul> <li>Keep hook_help() in place. Page-level (route-specific) help topics are unchanged.</li> <li>Add a new Help system that would co-exist, using config entities</li> <li>Each module, theme, or profile can provide multiple topics in config/install or config/optional</li> <li>Only topics marked as "top level", which is a config property, are listed on the help page; others are found through links and eventually/hopefully search.</li> <li>Site administrators can create more topics and organize them into a hierarchy</li> <li>Topic authoring will be through a user interface, and exported as configuration, so non-programmers can easily write and contribute help</li> <li>Topics will be broken up in configuration YAML into paragraph-sized chunks, for easy translating</li> </ul> <h3>Other proposals</h3> <p>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:</p> <ul> <li><span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-17"><a href="https://www.drupal.org/project/drupal/issues/402404" title="Status: Closed (outdated)">#402404: Use approach like D7 Advanced Help for the Help module</a></span> -- Proposes to add essentially the <a href="https://www.drupal.org/project/advanced_help">Advanced Help module</a> 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].</li> <li><span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-3"><a href="https://www.drupal.org/project/drupal/issues/2590319" title="Status: Closed (duplicate)">#2590319: replace hook_help with Help Plugin</a></span> - 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.</li> <li><span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-3"><a href="https://www.drupal.org/project/drupal/issues/1918856" title="Status: Closed (duplicate)">#1918856: Put each module's help into a separate Twig file</a></span> - 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].</li> <li><span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-3"><a href="https://www.drupal.org/project/drupal/issues/2188753" title="Status: Closed (duplicate)">#2188753: Get rid of hard-coded markup in hook_help() implementations</a></span> - Proposes several ideas for resolving [markup] and [authoring]. Not to the point of a patch yet.</li> <li><span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-1"><a href="https://www.drupal.org/project/drupal/issues/102254" title="Status: Active">#102254: Add an administrative search feature</a></span> - Proposes adding a way to search help, as well as administrative page titles.</li> <li><span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-1"><a href="https://www.drupal.org/project/drupal/issues/2701289" title="Status: Active">#2701289: Glossary to extend the Help system</a></span> - Glossary.</li> </ul> <h2>Process and where to find it<br> <h2> </h2></h2><p>This proposal was previously a core issue: <span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-5"><a href="https://www.drupal.org/project/drupal/issues/2351991" title="Status: Closed (won't fix)">#2351991: Add a config entity for a configurable, topic-based help system</a></span>, 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: <a href="https://www.drupal.org/sandbox/jhodgdon/2369943">Configurable Help</a>, which works fine, has automated tests, and has only a <a href="https://www.drupal.org/project/issues/2369943">few outstanding issues (mostly feature requests)</a>.</p> <p>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 <a href="https://www.youtube.com/watch?v=X30_HwaxOxk">demonstrated and discussed on 14 Nov 2017 at a Drupal Usability Group meeting, which was recorded on video</a>.</p> <p>This Sandbox module would be added to Core initially as an Experimental module -- issue for that: <span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-7"><a href="https://www.drupal.org/project/drupal/issues/2920309" title="Status: Closed (fixed)">#2920309: Add experimental module for Help Topics</a></span>.</p> <p>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: <span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-17"><a href="https://www.drupal.org/project/drupal/issues/2687107" title="Status: Closed (outdated)">#2687107: Reorganize topics into sensible outline, and/or write more topics</a></span> (this can be moved to Core as this initiative moves forward).</p> <p>Another thing that would need to be done, probably after the initial Experimental commit, is to add a Search feature. Issue for that: <span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-7"><a href="https://www.drupal.org/project/drupal/issues/2664830" title="Status: Closed (fixed)">#2664830: Add search capability to help topics</a></span></p> <h2>Proposal roadmap</h2> <p>Tasks to be done:</p> <ol> <li>Make a Core patch that adds the existing Sandbox module to Core as an Experimental module. Issue: <span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-7"><a href="https://www.drupal.org/project/drupal/issues/2920309" title="Status: Closed (fixed)">#2920309: Add experimental module for Help Topics</a></span> -- postponed until this initiative gets approval.</li> <li>Full usability review. This has been reviewed already by Yoroy on #30.</li> <li>Write some more Core help topics -- see issue <span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-17"><a href="https://www.drupal.org/project/drupal/issues/2687107" title="Status: Closed (outdated)">#2687107: Reorganize topics into sensible outline, and/or write more topics</a></span> on the current Sandbox module. This could be done after the module is in Core as a Beta Experimental module, before its full release</li> <li>Add a search feature. This could be done during the Beta phase, after initial Experimental module commit and before full release. Issue: <span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-7"><a href="https://www.drupal.org/project/drupal/issues/2664830" title="Status: Closed (fixed)">#2664830: Add search capability to help topics</a></span></li> <li>Consider whether other features would be desirable, such as index or glossary.</li> </ol> <h2>Not in scope</h2> <p>Index and glossary are probably not in scope but could be added later.</p> <h2>Related work</h2> <h3>Existing core features</h3> <p>a) hook_help() provides module overview topics and top-of-page help blocks. However, see the Problem section above for deficiencies in this system.<br> 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.</p> <h3>Open core issues</h3> <p>None known at this time.</p> <h3>Contributed projects</h3> <p>Sandbox module exists, by jhodgdon, who is attempting to get this in Core and resisting making it a full Contrib module. See above.</p> <h2>Team and resources</h2> <ul> <li>Initiative coordinator: jhodgdon and/or Amber Himes Matz</li> <li>Making the initial Core patch: jhodgdon</li> <li>Core module maintainer once it's in Core: Amber Himes Matz and/or andypost</li> <li>Usability review: yoroy has done a quick review already</li> <li>Writing more help topics: jhodgdon and Amber Himes Matz can write and/or coordinate volunteers (both coordinated User Guide project)</li> <li>People who have said on this issue that they want to help: gnuget, vijaycs85, andypost, jhodgdon, Amber Himes Matz</li> </ul> <h2>Signoffs</h2> <h3>Signoffs needed</h3> <p>Idea: Product manager: dries or webchick, yoroy, G&aacute;bor Hojtsy<br> Plan: Release manager: cilefen or xjm<br> Plan: Framework manager: effulgentsia, catch, alexpott, larowlan, platch</p> <h3>Also, consult these maintainers</h3> <p>Help subsystem maintainer: (none currently)<br> Documentation maintainer: (none currently)</p> <h3>Signoffs given</h3> <p>Idea: Product manager: signed off by yoroy in comment #66<br> Plan: Framework manager: signed off by larowlan in comment #64<br> Plan: Release manager -- (not yet)</p> > Related issue: [Issue #2516902](https://www.drupal.org/node/2516902) > Related issue: [Issue #2587469](https://www.drupal.org/node/2587469) > Related issue: [Issue #2188753](https://www.drupal.org/node/2188753) > Related issue: [Issue #402404](https://www.drupal.org/node/402404) > Related issue: [Issue #2590319](https://www.drupal.org/node/2590319) > Related issue: [Issue #1918856](https://www.drupal.org/node/1918856) > Related issue: [Issue #2351991](https://www.drupal.org/node/2351991) > Related issue: [Issue #102254](https://www.drupal.org/node/102254) > Related issue: [Issue #2205713](https://www.drupal.org/node/2205713) > Related issue: [Issue #2697791](https://www.drupal.org/node/2697791) > Related issue: [Issue #2698035](https://www.drupal.org/node/2698035) > Related issue: [Issue #1885192](https://www.drupal.org/node/1885192)