Remove "More Help"

Here's the simplest solution.

It could theoretically fail if a a module tried to implement more than one hook_help('admin/help#something') or if it did not follow the convention of using modulename as something. But in practice, this code covers core's actual usage, AFAIK.

And here's my version.

Move the stuff up inside the first if(), it's much easier to grok that way.

Let's add a test for good measure.

Changing title to describe the actual problem better.

bdragon's re-organization of the function does indeed make it more readable, and the test should help avoid similar bugs.

Marking critical, because we definitely don't want the alpha to ship with missing help links.

Awesome! I'm glad we won't break this yet again the next time we get crazy with paths. :)

Committed to HEAD.

A quick addition to the api documentation to make explicit what the code does.

Your help doc patch has a spelling error "pathes" instead of "paths". Also, we don't normally put a line break in the middle of a paragraph -- lines in help files should wrap at nearly 80 characters. So I would start the new sentence on the same line as the end of the previous sentence.

I also don't think the sentence you added is very clear... maybe it can be clarified somewhat?

Additionally, this appears to have introduced a regression. If you go to a page like admin/content, now it's showing "More help" even when there isn't help to begin with.

Let's fix this bug, as well as get some tests to document how this ought to be working.

arianek suggested to me by email this week that the words "More help" should be changed anyway, since it's misleading. She hasn't apparently filed an issue...

The link really points to the main module help. Her suggestion was to make it say something like "Help for the xyz module", instead of "more help", because it doesn't really provide more specifics for the page you're looking at.

So if you change the name of the link in this manner, it will make more sense *and* point every page to the help screen for the module in question.

That makes sense, but this still looks crappy:

I'm also not sure how jazzed I am about exposing the concept of modules to every user with access to something in the administration panel (there is no separate "access module help" permission at the moment; it's based on administration page access).

Since there are a lot of inter-tangled issues here, let's re-purpose this one since we have all interested parties' attention.

Proposal:

- Remove this "More help" functionality altogether, since as Ariane points out, it is not in fact "More help" at all. In D7, we now link to these pages right from the modules page, so I think that's as contextual as we need for the purposes of these pages.

- Add an explicit permission around access to these pages so it's not tied to "access administration pages" (this will require an upgrade path). User 1 would still see these pages, as well as anyone in the admin role. Disadvantage is that people like content editors would no longer see a "Help" link in the toolbar. Advantage is they'd have no idea what to do with anything in there anyway. :P

Sound good?

Since this is a fairly major functionality change, I would like to get this done by Friday.

Bear in mind that when communication happens via e-mail, IRC discussions, etc. the rest of the community is left out of it. Please have discussions like this in the issue queue in the future.

I'm ambivalent about the permission changes. IMO, the stuff under "Help" makes no sense to anyone who isn't a site builder, and right now it's accessible to everyone with access to any page in the admin panel, even if it's only the comment approval page, for example. But this is also the case in D6 and below, so it's not critical to do anything about this here.

There are locations where the More help has certain value, I agree it doesn't at most places make sense. But it does in some, could we special case those? And only have them show where it makes sense? To me that sounds more like something "designed" :)

There is absolutely no reason why it would be bad for usability, to show up in some places but not in others. This is totally dependant on the context, I would not see why people would be confused by the fact that, there are only a few places that have a More help link - only if they would start to see it as a pattern it will be confusing - so places where I imagine are :

Actions
Taxonomy
Text formats

Again what we should be aware of, that contrib might want to expose these links. Special casing in this case if implemented well should not be any trouble for contrib.

Hey - yeah, that totally wasn't me (must have been Shai!), this is the first I've heard about this.

That said, I am basically a +1 on what @webchick is saying in comment #13. The help content only makes sense at this point for site admins. So whatever contextual help links there may or may not end up being, should really be restricted from *all* users being able to see it.

(To me this brings up the issue of supporting end-users more with some parallel help content for them, but that is a whole 'nother can of worms, perhaps for D8!)

K, Bojhan has a good point. There are indeed places where it is definitely prudent to have the "More help" link to show up.

How about this? If the current path matches the path specified by the module as its "configure" path (e.g. admin/structure/block for Block module), then output the More help link.

Also, given that this actually /does/ have a point, I think we can scrap the permission change from the proposal.

No, I do not want to expose the concept of modules to content editors directly. I also really don't want to lead this issue off track nit-picking the label, because it's alpha critical and we need to get it fixed within the next day or so. So let's leave the label as "More help", because that's what it is, as long as the logic is changed accordingly as outlined in #20.

Correct. It'd remove "More help" from any page that is not designated as "the" primary configuration page for the module. (See the "Configuration" links on admin/modules)

@Shai Could you provide a patch that does what we are talking about? I am not sure how to do this, and we could probably leave renaming the label to another issue - to avoid killing to many kittens in this issue.

Yes, we are not debating the string change here. Follow-up for that. Let's please just fix the bug.

I'm working on it right now...

Re #13, the link on 'admin/content' is not a regression, it's a documented 'feature' that's been there all along.

See node.module node_help() :

    case 'admin/content':
      // Return a non-null value so that the 'more help' link is shown.
      return ' ';

*cough* *hack* *cough*

As for the ugliness in the screenshot, that's a bug in contextual links, AFAICT. (It's still an issue under the new paradigm on admin/config/people, for example.) I could have hacked the CSS to shift the help link, but didn't feel comfortable with that for this patch. Let's figure that out in a follow up, because it's a more general problem.

For the record, I'm in favor of renaming to 'more information,' but willing to concede that to a separate non-critical issue, so I left it alone.

The attached patch implements the current proposal. Since this makes the node_help hack ineffective anyway, I removed it.

ack sorry, just ignore my comment, i didn't understand what was going on. i'm just gonna stay out of this one, i don't have time to get caught up enough to give proper input for another week!

RE: Shai vs. arianek: Yes, it was shai, and sorry about the confusion. Anyway, everyone is here on the discussion now.

My thought: Completely remove the More Help link as an automatic link.

If a particular screen needs a link to the module's help page, put the link in the text of the help.

Oh, snap. +1 to jhodgdon's suggestion. It's the only sensible thing to do; based on Shai's report in #33, it seems you clear that we can't programmatically derive when the link is appropriate, and the code to do so right now is quite verbose. Maybe we can come back to auto-generation in Drupal 12 when Drupal can read and parse the help text and make its own decisions. Hmmm... ;)

I haven't looked into it, but probably something like that. It'd be a place to start anyway. :)

I'm going back and forth on this. My first reaction was to agree, but then I thought, do we really want to make it harder to find what information we do provide? IMO, the solution to sub-optimal help text is not to hide it, but to improve it, or at least to improve it's identification.

I'll hazard suggesting that this brings us back around to the idea of re-naming the link. Maybe 'Information for Administrators' or 'Administration Guide' ?

Here's another question which might solve our UI collision woes -- is it possible to use Contextual Links to provide the link? That gives us another layer of permissioning, as discussed earlier -- 'the 'use contextual links' permission.

Whatever we do, I think, as a general principle, removing links to documentation is bad. People can always ignore what's not useful, but not if they don't know it exists.

So have we identified a list of config screens that really could benefit from a link to their respective module help pages?

Patching the code to remove the "more help" links is relatively easy (#31 patch, sections for menu.inc, node.module, and help.text: take out the - lines and don't add the + lines. Leave out the rest of the patch).

But in my opinion, we should also patch the contextual help sections to add a link where needed (e.g. that part of node.module from the #31 patch, which added a link from admin/content to node.module help).

Do we have a list of pages where that would be helpful, besides admin/content?

Sorry for the confusion.

Here's a patch that removes all the More Help links.

I guess if we decide a particular admin screen needs a link to the module help page, that is a separate issue.

@jhodgdon I would think so too.

In that case, can we mark as RTBC? Shai and I both confirmed the patch works, and I think (?) we are all agreed now that it's a good idea. Speak now...

Shai: your new issue is a duplicate of #681814: Shortcuts Config Page in Desperate Need of Help-text (just marked as such). At least I think so.

Very good. Props to jhodgdon for better design through removing things :)

BAM. Committed. Thanks, folks!

OK, now how's about a follow-up issue where we try and quickly come to consensus about what pages deserve linking off to their own modules' help page, so we can make the necessary string adjustments before Friday?

I think Shai and I kind of agree that there are very few, if any. Module help is an overview, not details that will help someone editing a page.

I just posted a follow up patch to give us a "more help" link for the Forum module once we go into the configuration screen. http://drupal.org/node/728644#comment-2664678