hook_help(): Top of page help sections can't link to help pages without a fatal error or checking for help module

2e use a tour instead?

The combination of 1b for most + 2e for the rest, which would make 3 N/A, seems good to me, but would be good to get opinions in here from people who've been involved in Drupal usability studies.

Tagging for UX team feedback. I do think contextual help is a very useful feature, esp. for custom admin pages. And even within core, it's a simple way to introduce complex terminology to people on the main admin listings. Tour module doesn't really work for me as a replacement, because I might need to click X things to figure out the definition I'm looking for (and after clicking all X of them might find out it wasn't defined for me after all :\) as opposed to quickly scanning 2 sentences. (I also find Tour's help link completely buried and always forget to look for it, but that's a separate issue.)

OTOH, now that there's the "help" region (or whatever it's called), one can create their own custom "system help" block(s) if they wanted to (although it's a much bigger rigamarole). In Olden Tymes™ system help linked off to /admin/help/foo if such a page was defined for the module that defined the current admin listing. With Views this gets much trickier though.

Personally, I don't find the problems in this area particularly compelling enough to start re-jiggering everything when we're in the phase of the release when we're trying to stop changing things just for the sake of changing them. "It's weird" is definitely true, but it's been true since at least Drupal 4.6, so...

Btw, we could solve at least 1, 2, and 3 by simply moving the system_help block to the Help module as "help" block and enable it in standard profile, and this wouldn't require changing any module developer-facing APIs.

#7, moving the help block to Help module, is the absolute minimum for D8 in my book.

Neither the page-level help nor the per-module help page resolves the needs of anyone; it neither provides answers for interested users, nor does it allow developers to educate about the real things that may need explanation.

We should have turned Help module into a dictionary/encyclopedia style Definitions module whose architecture is a definition list a long time ago.

Regardless of page and context, what's needed is the ability to map an arbitrary identifier to a defined term + description. Whether that identifier is a route name or a custom identifier (e.g., "user.role") doesn't matter to Definitions module; it simply maps a given identifier to a definition and returns it.

What that enables is plenty-fold:

Selective help

Placing a help block on a particular page into a custom region to show a specific, preselected definition.

Contextual help in e.g. forms

Rendered and exposed in whichever way you can imagine.

$form['machine_name'] = array(
  // ...
  '#definition' => 'entity.machine_name',
    // What's a machine name? Why should you care? Give good examples?
);

Inline-able + parse-able in text fragments (wiki-style)

Enter the [system path](url.system_path) to link to.

Re-usable

Let's stop to repeat ourselves.

You can create a [view](views.view) to list this content.

Page-level help

Where necessary/sensible, still supports summaries for page-level help. Just point to its definition.

Per-topic help

By design, definitions are list-able per module/topic/category/context in a definition list.

Learn all you wanted to know about Views? There: One definition list on the topic of Views.

In short, remove the hard binding to routes and modules altogether.

Stop adding help where no help is needed. Start to think in definitions. Many definitions. Tailored definitions.

@webchick maybe we could use tooltips as a way to introduce complex terminology? We're using one for the shortcut icon right now and there some discussion of using it elsewhere: #2207383: Create a tooltip component

My 2c. The concept of the help block, maintaining help separate from the controller its describing, makes no sense to me. It leads to outdated information since people forget it exists. Even solving that, the concept that block placement can effectively show any sort of contextually useful information also seems mistaken and a needless complexity.

1) Get rid of page level help (block/those entries from hook_help).
2) Following my feelings on 1), d) show information in the controller and e) use tour(and/or tooltips). b) does sound interesting in that we could do it by allowing a callback that could be shown in a popup when clicking on a placed help link or help icon. Much like the formats help does on text fields. But that is a new and likely complex system and a new feature so I would put it out of scope.
3) see 1)

I think the tour module could come closer to being a replacement if it had a view that marked all tips attached to page elements as clickable links. Clicking one would open the tip that has been placed there. Of course that still would not be quite as visible as the current contextual help is.

I've also seen a few introductions that show all the tooltips at once, for less linear screens. Both this and a tooltip on hover would be possible after implementation of #2207383: Create a tooltip component

There main issue I've noticed in Help in D7 is the long list of non-contextual items when I go to /admin/help in D7 which include, for 98% of staff users, 98% topics they don't have permission to do and no way to identify the 2% they do have permission for.

The Advanced Help which exists for Views in D7 is useful, although more content would be welcome.

#2348975: hook_help(): Top of page help sections can't link to help pages without a fatal error or checking for help module was a duplicate in terms of the possible options, but exposed a user-facing fatal error in core. I've marked that as duplicate since this already has the options outlined more clearly.

I like the conceptual idea of splitting contextual vs. module help, that could also be done in 8.1.x with two new hooks / config entities / whatever and hook_help() left in as a BC layer. And I'd really love to see #2265533: Review page-level help and make sure it's conceptual happen regardless, but jaunting off on a huge quantity of work with an unknown "definition of done" as a pre-requisite of solving a release-blocking bug does not seem like a good idea to me at this juncture.

Fortunately, this is pretty clearly not a release-blocking bug. https://www.drupal.org/node/45111 clearly states that "Issues that have significant repercussions but do not render the whole system unusable (or have a known workaround) are marked major." A fatal error if one module is enabled and another one isn't and you happen to click on a link is not critical. It's major. Workarounds are either enabling the Help module or not clicking the link.

So given that, we should do the least possibly invasive thing we can here, which as far as I can tell is this:

Move the block to the Help module, so if you disable Help you wouldn't have page-level help. This seems like an obvious thing to many of us, but it's not how it works now (for historical reasons).

Or am I missing something?

If we move the block, we'll probably need to update block instances once there's an 8-8 upgrade path, so adding tag.

1. +++ b/core/modules/help/help.module
   similarity index 97%
   rename from core/modules/system/src/Plugin/Block/SystemHelpBlock.php
   
   rename from core/modules/system/src/Plugin/Block/SystemHelpBlock.php
   rename to core/modules/help/src/Plugin/Block/SystemHelpBlock.php
   

   We should rename the class and the plugin ID to not prefix it with "system"

2. +++ b/core/modules/system/system.module
   @@ -720,10 +720,6 @@ function system_preprocess_block(&$variables) {
   -    case 'system_help_block':
   -      $variables['attributes']['role'] = 'complementary';
   -      break;
   

   This would need to go somewhere.

"Contextual Help" block might be more descriptive as to what it's actually doing.

Nice to see the tests passing. :)

I'm OK with the rename if we can get this in before the upgrade path is supported - it should have very low impact on contrib modules (most install profiles and themes are not porting at this point).

However once we support an upgrade path I don't think it's worth writing an update for.

Looks ready to me as well.

We need to update the new NodeHelpTest which was added in #2379595: node_help() broken for node add/edit form

So this makes the help text on the Explanation or submission guidelines field (help) of node type a bit interesting. It currently says "This text will be displayed at the top of the page when creating or editing content of this type.". Should this now be a third party setting? There's not much more confusing than adding text here and it not appearing.

Agreed that that's a pre-exisitng problem, and we can fix it in another issue with moving the text to the form controller.

+++ b/core/modules/help/src/Plugin/Block/ContextualHelpBlock.php
@@ -16,14 +16,14 @@
+ *   id = "contextual_help_block",
...
+class ContextualHelpBlock extends BlockBase implements ContainerFactoryPluginInterface {

So now instead of having a misleading name prefixed with system.module, we now prefix it with contextual, yet another module? Why not just call it help_block and be done? It is in help.module, after all.

Thanks.

Is "The System Help module will only be available if the Help module is enabled, which is probably what people expect anyway." the only interface change?

@Bojhan yes that's the only change in the interface - the block previously existed all the time, now it's only if help module is enabled.

Good to see this come to a pragmatic solution, lets do it :)

Yep. Committed/pushed to 8.0.x, thanks!

Let's still do #2265533: Review page-level help and make sure it's conceptual to get rid of any pointless text that appears in the block.