Deprecate hook_help() and combine with Topics

I raised this (and the help topics patch) again with release managers and @catch advised that he'd like to see a more explicit plan here that had steps for a contributor who wanted to take it on once the other patch landed.

So should we repurpose this as a meta and provide instructions for how we'd tackle it (e.g. perhaps step one would be an audit to identify topics we need and where each hook help maps into said topics)? i.e. split step 2 from the issue summary into smaller chunks.

Updating this issue with conversation with @xjm and @benjifisher at the DrupalCon Seattle sprint.

One of the release managers' (xjm and catch) concerns is how to manage the duplicated help. (Module overviews in hook_help and in a Help Topic Twig template.) Worst-case scenario is that we do not finish the roadmap in time for the 8.8 release, and then we have to maintain the new Twig templates with any changes to the existing core modules (new modules, deleted modules, changes to `hook_help()`) for existing modules).

Can we think of a way to check for changes to a core modules' hook_help() diverging from the contents in the corresponding topic Twig template? From the release managers' perspective (as I understanding it), having a plan for dealing with this is essential before the experimental module issue (2920309) can be committed.

I worked on the original hook_help() patch WAY back in the day #26139: Admin help in core modules, and the way we managed this was to keep the "canonical" version of the docs on Drupal.org, and write a script to dump it into the proper format. That might be the way to do it here, both for hook_help() as well as the topic-based help, since it reduces the barrier of entry to hit "edit" on a page (or read it directly) vs. write a patch.

Sorry, yes, I understand (and wholeheartedly approve!) that it's not a 1:1 ratio of hook_help() to topics. I was more getting at a possible way to both work on / review this iteratively and also do an "all in one patch" without overwhelming anyone.

@xjm @catch We've tried to address your concerns about content duplication and I believe we have a good commitment and plan to deal with the transition. See #11 for links to the relevant issues. Pending any other issues that come up in a more thorough review of the patch, does this "unblock" the release managers' earnest review of #2920309 Add experimental module for Help Topics?

This is a great step and i'm strongly for deprecating the module-help-page part of hook_help. That's why i added #3048641: Let module help fallback to help_topic:mymodule.about (before i realized this issue, so this may or may not be merged here.)

For the help-block part of hook_help though, i'm not so sure. If we just want to show mostly static help text on determined routes, we might add something like a "applies-to-page" meta tag on a help topic. But what about dynamic content on dynamically determined routes/paths? Of course, many of such use cases can be realized by altering page content, a form, or providing a block. What this does not give us is the standardized semantic context of the help block. But i think we can live with that out-of-the-box semantics, given that having dedicated blocks may offer even more semantic context. So all in all, i strongly welcome this.

Also see #3048650: Add "Relevant help topics" block (or re-purpose help block).

I think there are different points to it, and we have to separete "hook_help" from "the help block".

As system architect i like the standardized design feature of the help block. The theme adds some styling that makes clear "This is some additional helpful information for this page". Emotionally, i really like the help block.

Also, Drupal is component lego. If i want to add some information to a page that i do not control, where do i go? I have no idea about the general form structure. If i just add some text on top, i probably break some design. In this situation, the help hook/block is a cozy warm standard place to use. The designer knows it's there and that something may be in it. We often use it to add additional info to content add/edit forms or config forms controlled by other components.

In other words, we could live without that, but my gut feeling is, we would reinvent a kind of replacement soon.
(Which does not mean i start fighting for hook_help, just thinking aloud. And who knows, maybe the replacement is a win.)

Tours are a great feature, but even for sighted users, they have accessibility issues: You can't overview them and scroll to a particular point of information.

It's the same why i usually prefer a writeup over a video.

As a fallback we could add "help_deprecated" module to maintain BC for d9/10

Created issue #3067614: Convert filter, ckeditor, editor module hook_help() to topic(s) as part of a first-time contributor workshop, feedback appreciated.

#16 - #20:

There are significant accessibility problems with tour module. At the moment it's really only usable by sighted people, using a random access input device (pointer, maybe speech control).

Replacing the help block with tour should be blocked by #2961001: [META] Improve accessibility of tour module. I've left a detailed list of problems there, together with some ideas for how to address them.

If a page has more than one tour, how does the user know which tour they are going on? It sounds like it will need more start-tour buttons, and those tours are going to need names to distinguish them. Otherwise they are... mystery tours!

#19:

You can't overview them and scroll to a particular point of information.

Can you elaborate on this please, over at #2961001: [META] Improve accessibility of tour module?

It sounds like it might overlap with a suggestion I made there, for a way to indicate that "extra help is available for this thing".

--

One thing that strikes me about tours, is that they assume there's something to point at. That's OK for various controls on a page, but it doesn't help with the overall question: "what is this page for?". That isn't always easy to say in a short page title, so having some preamble to a form seems like something that there will always be a need for. (It doesn't have to be a block though; FAPI #markup will still be available.)

Moreover it will use other library

As all topics ready

Is there an issue somewhere for the help block help, or is this that issue?

I bet this issue is about to deprecate the hook_help() and the help block (help sections are rendered via \Drupal\help\Controller\HelpController::helpMain()), gonna hack on it

Yes, help block needs own issue

First child issue is done, so now waiting to consider help topics stable

Updated issue summary.

This issue will be meta is we consider it actionable, still not clear how properly transition from requiring help topics instead of hook help

The core's kill-switch for documentation gate in #3074040: Move testing of help topic rendering into child of GenericModuleTestBase (I re-parented it)

FWIW, I tend to use hook_help significantly to document the specific behaviors of modules on various pages. The important point here is that this kind of help is contextual and may contain live data. See for example https://git.drupalcode.org/project/g2/-/blob/8.x-1.x/g2.module#L305 where the help text is complemented by arguments from the current context.

A nice workaround could be if help topics could receive a context provided by some service, maybe defining injection in the frontmatter.

A nice workaround could be if help topics could receive a context provided by some service, maybe defining injection in the frontmatter.

I imagine @fgm is not the only one to need this. Sounds like "Allow help topics to get context defined in frontmatter" should be opened as a child issue of this one? @fgm do you want to open the issue, or should I? In either case, I'm interested in more details as to what you are looking for, and if you could provide examples of your modules that use context in their hook_help() implementations. Thank you.

@Amber Himes Matz after converting help in G2 help to Help Topics (see https://git.drupalcode.org/project/g2/-/blob/8.x-1.x/g2.module#L305 for the original version, and https://www.drupal.org/files/issues/2023-08-20/3382138.patch for the converted version, still under review) I'm no longer convinced this is so much needed: a single helper providing access to a \Drupal instance would enable access just about any service by calling all \Drupal static methods as instance methods on that instance, and specifically \Drupal::service() thus enabling advanced templates to access just about any service without making the frontmatter more complex.

Still think this is worth a followup ?

Looks it need another yaml file to maintain "binding" of topic to routes and paths at least, like menu system doing for local actions and tasks.

Other option is contextual module in core which is also using ContextualLinks render element and manager with alter hook