We need less ambiguous help topic labels

Hm. Do we really need context? I would think that help topic labels would be long enough (not just one word usually) that they would not need context. My understanding is that context is only needed if the text being translated is ambiguous, but good help topics would not have ambiguous titles. They should be things like "Creating a feed" or "Placing blocks" etc. ???

The other problem with adding context is that on #3037229: Extract help topics label from meta tag in Twig files we are making sure that the help topic label meta-data gets added to localize.drupal.org. So unless we put the context hard-wired also into POTX, the string translation will not work. Which is to say, if it gets added in the code in HelpTopicDiscovery class (this patch), but the context is not in the PO database that someone downloads from localize.drupal.org, then when the page is translated into another language, it will not match context and the title will not be translated.

My feeling is that we should not put a context on the topic labels. I really don't think they need context if they are good labels.

Here are the label meta-data lines in the help topics that we put in the original experimental module patch:

core.config_basic.html.twig:<meta name="help_topic:label" content="Changing basic site settings"/>
core.config_error.html.twig:<meta name="help_topic:label" content="Configuring error responses, including 403/404 pages"/>
core.maintenance.html.twig:<meta name="help_topic:label" content="Maintaining and troubleshooting your site"/>
core.menu_overview.html.twig:<meta name="help_topic:label" content="Defining navigation and URLs"/>
core.security.html.twig:<meta name="help_topic:label" content="Making your site secure"/>
core.ui_accessibility.html.twig:<meta name="help_topic:label" content="Accessibility features"/>
core.ui_components.html.twig:<meta name="help_topic:label" content="Using the administrative interface"/>
core.ui_contextual.html.twig:<meta name="help_topic:label" content="Contextual links"/>
core.ui_tours.html.twig:<meta name="help_topic:label" content="Tours"/>
help_topics.help_topic_writing.html.twig:<meta name="help_topic:label" content="Writing good help"/>
shortcut.ui_shortcuts.html.twig:<meta name="help_topic:label" content="Shortcuts"/>
user.security_account_settings.html.twig:<meta name="help_topic:label" content="Defining how user accounts are created"/>

I don't really think these are ambiguous. Most are fairly long. The three that might be are "Contextual links", "Tours", and "Shortcuts". All three of these are already in the Drupal Core POT database on localize.drupal.org without any context (and with the same meanings as here). So... I think we are OK. We should maybe instead document somewhere that the topic title names should be long enough to not be ambiguous, and maybe change the titles of these three to something like "Using contextual links", "Viewing tours", etc.?

Some notes from Slack conversation about this:

Gábor Hojtsy (he/him) [1 hour ago]
Context should be used to disambiguate the meaning of a string not to explain where it came from / is being used
jhodgdon (she/her) [1 hour ago]
We could add another metadata we could read that would give us the context.. So we would have another meta tag like help_topic:label_context
Adding string context for translation wouldn't help in search results to explain what the pages mean
jhodgdon (she/her) [1 hour ago]
I think we should just strongly suggest that developers make good topic titles, and set the example by making good titles in core

So... Given that... I think we have two choices here:

a) Leave things as they are, and document that help topic titles should tend towards being more verbose so that they are unambiguous in help search for instance.

b) Give help topic writers the ability to disambiguate the titles by adding another meta-data item to the top of the topic, which would give the string context for the title. This meta-data item would need to be read by both this patch and the POTX module on #3037229: Extract help topics label from meta tag in Twig files. This would not help topics be unambiguous in search results.

I vote for (a), and using this issue to add documentation and fix the 3 titles "Contextual links", "Tours", and "Shortcuts" shown in #5 so that they are longer and more descriptive. The existing documentation on writing topics is in core/modules/help_topics/src/HelpTopicPluginManager.php as well as in core/modules/help_topics/help_topics/help_topics.help_topic_writing.html.twig.

Here's a quick patch for option (a).

We had a test that relied on not having the Shortcuts module enabled, then enabling it, and verifying that the shortcuts topic title is shown. The title changed, so the test failed. Fixing test fail.

Missed another line in the test where it clicked the "Shortcuts" link. Just two lines down from the previous interdiff.

Actually, let's wrap this issue up into part of a larger effort to clean up the existing topics: #3072312: Review/fix/delete existing help topics. I'll add a note there about making sure the titles are not ambiguous, and also on #2687107: Reorganize topics into sensible outline, and/or write more topics