During the usability study, many participants turned to the help page when they needed help, but struggled to find it. The alphabetically sorted help topics don't give any indication of what topics are important and what topics.

It just jumps around from the obtuse to the very basic.

Proposed resolution

Let's add a little more structure and hierarchy to this page.

Remaining tasks

Design the new help page heirachy
Discuss the best way to allow modules to insert themselves into this new page structure

User interface changes

A more helpful help page

API changes


Data model changes



cilefen’s picture

tkoleary’s picture

Let's add a little more structure and hierarchy to this page.

Is, I think, stating it a little too mildly. What we should be doing is more like completely reimagining a more sensible and task based hierarchy.

Off the top of my head it could look something like:

Getting started with a new site

  • Getting around the administration pages
  • Setting basic global configuration

Building a structured content model

  • Content types and how to build them
  • Using relationships to link related content
  • Using Display Modes to show content differently for different pages

Writing and editing your content

  • Configuring the WYSIWYG editor
  • Adding and editing content
  • Managing publishing settings
  • Using the content list page to browse and bulk edit

Managing visual design

  • Themes and how to install them
  • Working with images and media

Page layout and blocks (everything that's not the main content)

  • Where blocks come from and how to make them
  • Placing blocks in a layout and setting visibility

Planning how visitors navigate your site

  • Menus, how to create arrange and add links
  • Taxonomy, creating categories to organize content

Modules. Extending the functionality of Drupal

  • Finding modules
  • Installing modules and dependencies
  • Removing unneeded modules

This may not have everything but I think this is about the right amount of info for the top 2 levels. More would be too much cognitive load.

LewisNyman’s picture

@tkoleary This looks good :) I wonder how much this overlaps with the structure of the Drupal 8 user guide?

tkoleary’s picture


While that sounds sensible at first I think it might not be the right approach because both the user and the task may differ.

Users of a guide (or a book, or a video) are by definition invested in learning and understanding Drupal and are therefore more likely to be, site builders, themers or developers. Users of help are more likely to be editors or authors purely by the fact that they needed help. Developers, themers or site builders would be more likely to go to the documentation.

These two "metagroups", let's call them Dev/build/themers and Edit/authors have very different levels of knowledge, not just about Drupal but about technology and development practices in general. Dev/build/themers know what documentation is and where to find it. They know how to hunt down the right information in a wide variety of sources like stack overflow,, or a Drupal book or guide.

Edit/authors probably do not, help is the first place they will go.

Their task is also different. They don't want to improve their general knowledge, they have an *immediate problem* and they need a solution. A guide does not need to be concerned with how quickly a user can find a topic, it can be exhaustive and organized chronologically, by degree of difficulty or by some other factor.

Help needs to be quickly scannable, with enough link scent to get the user to the answer. It should not be chronological or exhaustive. It should elevate the most common problems in the most frequently used interfaces above others and word it's headings in a way that suggests an answer rather than a category. So where a guide category might be:

Understanding the Drupal theming layer

A help category should be more like:

How to change the design of your site

Having said that the two documents should certainly share nomenclature and thematic information and be similar in tone.

jhodgdon’s picture

The module-based system for hook_help() is very limited, because it is based on a hook. Thus:
- It only allows 1 topic per module, 0 per theme, 0 per profile.
- The topics are not really topics, they are just module descriptions.
- The help page that lists all the "topics" is really just listing all the modules that implement hook_help()

If you want an actually useful topic-based system for help, hook_help() is never going to be that system. So I think it would be better to call this a duplicate of many other past *feature requests* for Drupal, push it off to Drupal 8.1 with the rest of them.

In particular, there's a working (well, it was at some point but probably would need a bit of an update now) system in this sandbox:

See Core issue
#2351991: Add a config entity for a configurable, topic-based help system
which tried to introduce this but missed the beta deadline by a hair and was deemed too big to go in. I fought it but sadly no one on the Usability team ever listens to me until the usability studies come to the same conclusion.

So although it's been a major problem forever that hook_help() is useless, we are stuck with it.

And I think this should be marked as a duplicate of that other issue. If you want hierarchy and topics, it's there. hook_help() is never going to get you there. It can be in 8.1.x but it is not going to be possible to do much in 8.0.x given that we cannot add features and there isn't much that can be done with hook_help().

tkoleary’s picture


The module-based system for hook_help()

Ahhhh. It's like I though I was talking to an overly literal support person but it was really just a chatbot. :/

Replace topics with config entities is indeed a better idea.

jhodgdon’s picture

I've filed a new meta issue to collect all the problems with the current help system and discuss the best route to fixing them; this issue is being added as Related there:
#2592487: [meta] Help system overhaul

Note that this is in the Problems section not Proposed Resolution, because this is stating one of many problems with the current system, but doesn't propose a specific resolution. Several of the existing proposals would solve this problem.

jhodgdon’s picture

See also #2661200: Make admin/help page more flexible, and list tours on it, which will at least tell users that the alphabetical list they are seeing is "module overviews". I'm still working on the configurable help topics (which will have a hierarchy) as well.

yoroy’s picture

Issue tags: +Needs design
jhodgdon’s picture

Version: 8.0.x-dev » 8.2.x-dev

Note: #2661200: Make admin/help page more flexible, and list tours on it got into 8.1.x. There is a screen shot there of the new help page, which at least makes it clear what is on the current help page. Also, Tours are listed.

And... I do not think that we can make the current hook_help() into a topic-based help system. See comment #5... we would need something like the topic-based config entity system that I have working in a sandbox at

I'm trying to figure out whether to release this now as a contrib module or work on getting this into Core in 8.2.x, along with some topics (possibly the outline in #2 or something more like the in-progress User Guide -- see

yoroy’s picture

Issue tags: +ux-hierarchy
jhodgdon’s picture


Where should we go on this?

As things stand now, the Help page now has a "Module overviews" section and a "Tours" section.

As noted above, if we want to have hierarchical help topics (an additional section on the help page), we can go with a config entity solution, which I've been working on -- well, actually, I have a working system, but it's not in Core yet. The existing hook_help system for module overviews is not very adaptable to having a topic-based help system, as discussed above.

Status of my sandbox project for config entities for help:
- I spun off part of the project into a separate Core issue, which is blocking the rest at the moment. There is a patch, which has finally been reviewed once; waiting for more reviews and/or RTBC. #2697791: Add Plugin system for abstracted HTML-formatted text.
- The rest of this is in a sandbox project ; after that blocker issue gets done, I will make the sandbox (again) into a Core patch on #2351991: Add a config entity for a configurable, topic-based help system.
- In the sandbox, I've started working on some Core help topics; the issue for that is #2687107: Write some core help topics. I am going to look at the proposed outline in comment #3 here and direct my topic-writing efforts along some combination of that and the proposed outline that is currently in the issue summary of that issue.

If anyone wants to try this sandbox out, what you need to do is:
a) Get the patch from #2697791: Add Plugin system for abstracted HTML-formatted text.
b) Get the 8.x-1.x-2697791 branch of the sandbox module, put it into the top-level modules directory, and install the module.
c) Go to admin/help and you can see the top-level topics listed there (so far there are not many).
d) Go to admin/config/development/help and you can see the UI for adding/editing help topics.

If you find problems or have suggestions about the Config Help module, use the Config Help issue queue to report them --

If you have comments about whether that system will partly or completely resolve this issue, comment here.

If you have suggestions about what topics to write or how to organize them, comment on #2687107: Write some core help topics.

Version: 8.2.x-dev » 8.3.x-dev

Drupal 8.2.0-beta1 was released on August 3, 2016, which means new developments and disruptive changes should now be targeted against the 8.3.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

tkoleary’s picture

Priority: Major » Normal

Important but not major

tkoleary’s picture

Issue tags: +sprint

Important but not major

Version: 8.3.x-dev » 8.4.x-dev

Drupal 8.3.0-alpha1 will be released the week of January 30, 2017, which means new developments and disruptive changes should now be targeted against the 8.4.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.