Help File Fixup: shortcut and toolbar

I'm against having "powerful tool" in help text. Just say what the module does, don't offer opinions on how great it is. :)

As far as the other text in the help file, I was left with more questions than answers...

- Where do the shortcuts appear (which part of the admin nav)?
- How do they appear (are they a block? Does the theme have to know to display them? Are they specific to the Seven theme, or would other admin themes display them too?).
- What are the "sets" for? Why would I want to have more than one "set"? Are all "sets" displayed, or just some sets?
- Where's this "edit shortcuts" link I'm supposed to use?

Mind you, I've never tried using the Shortcut module, so I don't know the answers to these questions, but I thought maybe the help page should have told me?

I just was looking at the Toolbar module... It appears that the shortcuts area is displayed within the Toolbar.

So I think that the shortcuts help screen should mention that if you enable the Toolbar module, the shortcuts will be displayed within the toolbar. I don't know if there is a way to display them without enabling the Toolbar module... I'm going to file an issue on this, actually, as the shortcuts module is very confusing to me.

Correction: It looks like you can display Shortcuts either within Toolbar or as a Block.

Let's cover both of these here. There's a patch at http://drupal.org/node/637710#comment-2299946 which includes some toolbar help text which could be used as a base. The coupling between toolbar and shortcuts needs to be removed, however.

I wanted to reroll this but couldn't find how to make shortcut and toolbar help links appear (and they are enabled.) Hrm. Ideas? catch me on IRC...

Ummm... For me, when I enable the Toolbar module, I get a black bar across the top of the screen, with links (Dashboard and other admin stuff). Then when I enable Shortcuts, the configured shortcuts are displayed in a grey box just below the black bar. If I disable Toolbar, I can still display Shortcuts, but only as a block (either within Blocks or on the Dashboard).

I don't see how we can completely decouple the help for these two modules, given that Shortcuts are displayed automatically within Toolbar if both are enabled.

webchick: Can you please explain why you object to mentioning each module in the help file for the other? It does seem like they are tightly coupled, and that the best way to display Shortcuts is withing Dashboard.

Regarding the comment above that lisarex couldn't figure out how to edit shortcuts, I have added an issue here:
#647084: Missing shortcut edit and delete operations on shortcuts admin

So I'm hoping they will add a link to edit shorcut sets from the Shortcuts admin page. Assuming they do, here's a patch for both Shortcut and Toolbar.

This looks really good - made a couple small language tweaks, and added the handbook links. The handbook stub pages have NOT been made yet (I'm not sure where to put them in the book outline) but as soon as they're made, this can be RTBC'ed.

doh, would help if i attached the patch...

...and, handbook pages created and aliased. ship it.

Looks mostly good.

Users with the appropriate permissions can manage your shortcut sets, choose your preferred shortcut set

The "your" is confusing here and not really accurate (or at least not complete) - I'd delete the first "your" and replace the second with "a".

The Seven theme (enabled by default as the theme for administration pages) displays this link next to the page title ..... The other core Drupal themes do not display the shortcut link, as shortcuts are primarily for administration pages.

I wonder if we really want to spend so much time talking about the core themes in this help text - lots of sites couldn't care less about the core themes and what they do.

I'm also somewhat hopeful that via #646874: Modules like Contextual links and Shortcut cannot add to "template regions" we will get rid of this "Seven-only" behavior, but for now, it's there :(

If you have the <a href="@toolbar-help">Toolbar module</a> enabled, your shortcuts will also be displayed within the toolbar section of your page

I think this cross-reference is fine, but (I assume) the worry that @webchick had is that other modules (think admin_menu) might choose to display shortcuts as well, so we don't want to make the text too Toolbar-specific. Can we maybe say something like If you have certain administrative modules (for example, the <a href="@toolbar-help">Toolbar module</a>) enabled....?

The Toolbar module provides links to top-level administration menu items and displays the configured <a href="@shortcuts-help">shortcuts</a>

This cross-reference also seems a bit problematic, since the idea is that the bottom part of the toolbar (the "drawer") is available for any module to put links into. Maybe a similar rewording as above (where the reference to the Shortcut module would only be as an example) is possible here too?

I'll take a stab at fixing this...

I took most of your suggestions... One comment: I think that some mention of the seven theme needs to stay, because if someone switches admin themes, they may wonder why they no longer have the add/remove links, but I've removed some of the text.

Anyway, here's a new patch and screen shots.

Actually, try this one -- the .info file in the other one still mentioned shortcuts explicitly.

Looks great.

Fixed a couple small things:

1. The "About" heading wasn't showing for shortcuts (an $output = needed to be $output .=).
2. Changed one instance of "their preferred set of shortcuts" to "a preferred set of shortcuts" (for grammar nitpickiness).
3. Changed "by clicking on the close/open drawer link" to "by using the close/open drawer link" (pet peeve about not using mouse-specific words in help text).

The Seven stuff looks fine to me now - we can edit it further if we wind up getting that other issue in.

Question: Are cross-links between modules planned to be handled in any special way in the help text? It occurred to me that for example we are linking to Block module and Toolbar module administration pages from within the Shortcut help text, but we don't actually check if those modules are enabled, and if they're not, those links will be broken.

I didn't attempt to fix it here because I think it probably occurs elsewhere and if so can be its own issue.

Looks good.

Committed to CVS HEAD. Thanks.