Help.module should make use of the menu descriptions under the titles

Adding the descriptions as "captions" for the administrative menu links displayed on module help pages is a good idea.

Attached a patch providing the description underneeth the link.

Tested the patch and the results look great. To see the visual results please look at the two pictures that have been attached.

Sorry about the attached names... I changed the description for each but that didn't seem to work.

Changed back to 'needs review' due to me not understanding when to change status to 'RTBC'. Sorry for the inconvenience.

Looking at the screenshots, I'd agree this makes it much easier to decide where to click.

+++ b/core/modules/help/help.admin.incundefined
@@ -81,7 +81,12 @@ function help_links_as_list() {
+      $output .= '<div class="description">' . $module_info[$module]->info['description'] . '</span>';

Alright, reviewing the code, looks like a markup error here. :) Is it a div or a span? (Div is used on admin/config so I'd go with that.)

Crossposting #423724: Help landing page: what should be on it, how would it look..

New patch, fixes the div/span mismatch.

+++ b/core/modules/help/help.admin.inc
@@ -81,7 +81,12 @@ function help_links_as_list() {
+    if (isset($module_info[$module]->info['description']) && !empty($module_info[$module]->info['description'])) {

isset() not necessary if you do !empty() right after.

@scor is correct a simple !empty statement will do the trick because it also checks for NULL just like isset does.

The patch submitted at #9 works for me however we still need the fix talked about in #10.

Re: #13: Probably not. However, the entirety of the Help page is this way, so it's beyond the scope of this issue to change it. See also #423724: Help landing page: what should be on it, how would it look., and of course the D8 initiatives.

#13: adding_description_to_help_links_page-152482-13.patch queued for re-testing.

#13 Besides the "whole refactoring" posts, see eg http://drupal.org/node/232466 for at least wrapping the output in a theme function. That said, I see this as an easily backportable quicky.

I agree with #14 that theme-ifying the help module is not in-scope for this issue.

Unfortunately patch no longer applies.

error: core/modules/help/help.admin.inc: No such file or directory

Patch rerolled

UI change, so we need manual testing with screenshots, preferably embedded in the summary, so that the proposed change can be evaluated. What if the longer titles affect the layout?

This is currently filed as a feature request, which would make it blocked on thresholds, and therefore unlikely to be accepted before release. However, this seems to me more like it's intended to be a usability improvement. In that vein, let's tag it for usability review once the screenshots are posted.

Updated title to give clearer description of what is actually happeneing with this patch

Screenshots attached showing before and after.

Before patch

After patch

Updated issue summary.

Updated issue summary.

updated tags

Ah. If we're adding sentence-length text, does having four columns still make sense? I find that list kind of overwhelming as it's laid out.

Note that I don't think a complete overhaul of this page is in scope here, but something like #232466: theme help topics is probably a good idea as a followup (and still doable in this release cycle since it is lightweight and does not break BC). However, changing the CSS so it's at least just a single, scannable column seems important to me if we make this change. It's also a good idea in general to get rid of the columns, because they're not responsive. My recommendation would be to remove some styling to allow the help list to be a single, full-width list for now, and then refine both the design and the markup in a followup issue.

Thanks @realityloop for updating the title; that makes it clearer what's going on here. Can we also update the issue summary to reflect the current direction of the issue? (I've filed a core mentoring task for that.)

@xjm: is there any issue with making the colums be responsive? so it's a single column when on mobile layout and more when on tablet or desktop?

..Perhaps we should first make a patch with it as a single column, then look at making it more responsive.

it might also be better themed as a dl list, or maybe reusing the design of something like the modules page or something. If you have a bit of design/UX/frontend flare it would be great to see some mockups

Taking a stab at this here in core mentoring.

Now featuring a DL and only 1 column.

And that pic one more time

Here is a version that brings the columns back but is responsive to a degree. I started with two formats, narrow & wide (everything less than 960 and everything more than 960).

Here's one more with the breakpoint set to 768px, and some cleanup

Updated issue summary.

Reviewed code and tested in firefox/chrome/safari on OS X.

Interesting patch! Assigning to jhodgdon since it deals with the help system.

I'll take interesting :)

I like it!

The only thing I would say against this idea is that on most sites that I build, there are a zillion contrib modules in addition to whatever core modules are enabled. So, the list of help topics (which was already quite long without the descriptions) could become extremely long. I think that is why on the Modules/Extend page, in 8 we are hiding all of the stuff except the module name and maybe the version, right?

However, this argument is mitigated by the fact that if you come to the Help page, presumably you are looking for help, so in this case I think that adding the module descriptions is a Good Thing. Most people on phones or desktops have a quick way to scroll through a list, anyway.

One thing that occurs to me though... Do you think we need an accessibility test?
- Do people using a screen reader have a way to just hear the headings, or do they have to hear the descriptions, which would take a long time?
- Do people using keyboard or screen reader to navigate the page have a way to jump from item to item without landing on the descriptions?
- Do the entries in this two-column format on a desktop browser come out in alphabetical order to screen reader users, or are they jumbled together?
I'm setting this back to "needs review" until someone confirms that the new page is accessible.

The issue summary is slightly out of date as well.

LOL Sorry, I was in a hurry yesterday... I meant good interesting, not weird interesting. :D I like it! It's a really clever way to add more context to this mass of links without having to duplicate text unnecessarily.

@webchick - just playin :) @jhodgdon - About accessible or not, I do not know how screen readers will work but the DL divs should remain alphabetical. Ill test tonight and reroll if necessary as well.

OK, passed thru achecker.ca and tested with Voiceover and found some things:

Bad:
- The DT anchor text should 1) Be meaningful out of context & 2) identify the destination, so rather than "Block" it should probably say "Block Help"
- Using Voiceover on an iPad I couldn't skip the descriptions.

Good:
- The items are still in alphabetical order.

Thanks for the testing!

So I think that we can fix this by:

a) Updating all the links so that they have titles saying "%module module help".
b) Changing from using DL/DT/DT to using an LI list with H3 headers. In D7, the search results page was switched from a DL list to this format for this exact same reason. So the desired output would be something like this:

<ul>
...
<li><h3><a href="admin/help/foo" title="Foo module help">Foo module</a></h3>
<p>The description of the Foo module</p>
</li>
...
</ul>

Question: are we just listing modules here? The page heading says "items" or something like that... if we are listing both modules and other things, it seems like the link text should distinguish between "Foo module" and "Bar theme"? This would be good for both sighted and non-sighted users. I really have no idea -- can themes and distributions etc. have hook_help()? If they can and if we're listing it, then we should put the type in the H3 headers IMO. If it's just modules, than the page header should call them modules not "items".

Anyway, given the accessibility issues, I think we should rework the patch a bit. Thanks!

As part of the Midwestern Drupal Summit, I was assigned an issue summary update on drupalmentoring.org http://drupalmentoring.org/task/4166

Just a re-roll of #32.

I'm not sure this issue is actually alive as the last substantive update was just under 10 years ago, but I'm trying to give all "Needs accessibility review" a fair shake

The At support for description list elements is still incomplete in some ways, so an unordered list with headings would be my recommended approach. This also provides a nice way to see the shape of the list when screenreaders display the heading structure. The hierarchy makes it immediately clear that the list belongs to "help topics".

And just to bikeshed an issue that there may not be interest in anymore... I'm not sure that extra text is particularly helpful. It technically provides more info, but dilutes what is there. I'm guessing the goal of this was to prevent people from navigating to pages that didn't turn out to be relevant to what they needed. My suggestion, given that overlay has gone away since this issue was last touched, is to make each link open a modal with the help content. This provides a way to quickly check help items to see which one is relevant, without the computer and congnition drag of going to multiple pages then having to navigate back.