Well... I was inspired by Dries' speech to lend some of my thinking and time to improving the user interfaces and usability of Drupal for the next release. A very basic idea I had was improving access to help pages in a Drupal site.
Right now you have to browse to the administration page and then actually access the help page through the menu. You can't find a link on the page itself, which was confusing even to me just now when I was testing the current functionality! Once you get to the page (admin/help), you see a big list the combines help pages for contributed and core modules and then a glossary beneath it all.
Now, here's my simple idea. There ought to be a link/icon from the different menu pages and forms that leads to a relevant help page. Furthermore, I'd like to use HTML/Javascript to do any of the following things:
- Pop the help page out in a new window so you don't have to browse away (target="_blank").
- Let the user view the help info on a current page somewhere. (See the translation helper module.)
- Load the help page up in a Thickbox or some other sort of div.
- Let the user load the help window by pressing F1.
My rationale is simply that a link could be opened in a new window by anyone, but the lower end user may not know that they can do this and could end up browsing away from a form in progress accidentally.
This help window should automatically detect which help page needs to be shown. This can be handled by detecting which module defines the URL the user is viewing. Perhaps hook_help() can be extended further to make this all more useful.
It would be great to give site builders and module developers the chance to create custom help pages attached to different pages of the site or even individual tables and form elemebts.
I'd like to brainstorm on this a little more and get some feedback... If this gains some traction, I'll be happy to start coding.
EDIT: D'oh. After the fact, I just noticed some [more help] links on a few different pages in the admin menus. However, at present a few seem to be duplicated. I'll check out more and post back. I think a per field help icon that would expand some help text would be incredible.
Comments
individual issues
I think this is a great "best practice" but needs to be addressed module by module, patch by patch.
I know that I've created modules which hide their help and others that have prominent links to the help on the admin/settings page. So it's down to finding modules that make it hard to find the help and then filing bugs (ideally with patches) to fix those modules.
Note also that all of these links are exposed on the admin/by-module
--
Knaddisons Denver Life | mmm Chipotle Log | The Big Spanish Tour
knaddison blog | Morris Animal Foundation
Like this idea
I really like the idea of having a help page pop-up, instead of letting the user browse off the page.
I figured target="_blank"
I figured target="_blank" would be a bad idea. ; ) I'd be much happier using Thickbox, I was just trying to think of something to keep folks from losing a page if they were browsing w/ JS disabled. Thinking about it now, though... the kind of people that disable JS will probably know to open up a page in a new tab to prevent from browsing away. : P
Page template for helps would be good to put out as a "how to make your module help not suck" best practice guide.
Having a single page of help makes sense, and it can still work w/ per field helps I believe... just make the field a subject heading and navigate to an anchor there when the help window pops open.
More brainstorming:
I envision this usage being for more than just admin settings pages... how about for roles that have "help me" access with "show help icons" turned on in their profile would even see a little ? icon on a node creation form? Have it work for node creation forms and allow administrators to set custom help messages dynamically. (This would be great for site designers creating various CCK node types for client sites.)
Icons
In Barcelona morten.dk said he already made a bunch of icons for Drupal.
From a broader point of view I guess we could create a "how to make your module user-interface not suck" best practice guide (which should include recommendations for core).
Custom module?
One way to do this is by making a custom module that somehow finds out which help page relates to each form element and then use hook_form_alter or something to add a help link/icon after the element (much like the JS Tools date picker for the CCK date field) that pops up a Thickbox or whatever. The difficult part is finding out what help page relates to the field, and even what #anchor on that page to link to. Just thinking out loud, not volunteering to do this I'm afraid :)
ximo, custom module was what
ximo, custom module was what I was thinking. Obviously I haven't started coding anything yet, but it would be simple as you say. To figure out context, you can do a few things... in hook_help(), you already have to specify pages the help applies to, so we can work with that and maybe extend it somehow. That would take some more thinking, though.
civicspace admin theme
I remember back in the days when I was trying to break out the civicspace admin theme to a standalone theme for people to use as admin interface, I noted that they use custom tricks to identify which module an admin page is defined by, so they can adjust their standard (always present) help link. Although at the same time I also noted that their logic is in many ways broken (it is hard to know what module defined a link based on just the first path component, but definitely, this is the speediest way). Here is the code for brainstorming (note that this is pre-Drupal5 code, but their latest version from CVS):
<div id="admin-help">
<ul>
<li><a href="http://drupal.org/handbook" title="Drupal handbook">Drupal Handbook</a></li>
<?php
$help_loc = check_plain(arg(1));
$help_link = "?q=admin/help";
if ($help_loc) {
if ($help_loc == "settings" && check_plain(arg(2))) {
$help_loc = check_plain(arg(2));
$help_print = ucfirst($help_loc) .' Help';
$help_loc = '/'. $help_loc;
}
elseif ($help_loc == "help") {
$help_loc = "";
$help_print = "Help Index";
}
elseif ($help_loc == "themes") {
$help_loc = "";
$help_link = "http://civicspacelabs.org/home/CivicSpaceTheme";
$help_print = "CivicSpace Theme Help";
}
else {
$help_print = ucfirst($help_loc) .' Help';
$help_loc = '/'. $help_loc;
}
} else {
$help_print = "Admin Help";
}
?>
<li><strong><a href="<?php print $help_link . $help_loc; ?>"><?php print
$help_print; ?></a></strong></li>
<li class="last"><a href="?q=logout">Logoff</a></li>
</ul>
</div>
Comes from http://cvs.drupal.org/viewvc.py/drupal/contributions/themes/civicspace/p...
Help pop-up example
This is a nice and unobtrusive example (upper left corner):
https://bugs.launchpad.net/
A "pop-out" rather than a pop-up.
Too much explanation is bad
Have a look at /admin/build/modules. The top half of this page is used for a help text for first time users. It's fixed, you cannot make it go away.
For first time users this is okay. For advanced users this space is wasted. Just wasted.
My suggestion:
both accessible on all admin pages.
I like the idea of providing
I like the idea of providing space for two levels of help on every page, with the second hidden by default. Some guidelines for how to effectively write for these would be good.
The help section is organized with one page for each module. 'More help' links are added to admin/{section}/{module name} pages where
I think this might not be ideal. For example, admin/user/roles might want to link to the help section page for the user module, but 'roles' != 'user.' The purpose of the help section, its organization, and links to/from other parts of Drupal need to be reviewed.
A complete review of the help system needs to consider the documentation on drupal.org too.
Modules vs pages
Been thinking about this. Perhaps this is one of Drupal's usability traps: thinking too much in terms of modules.
I believe users are not so much interested in modules. They are interested in pages. What exactly can I do on this page? How does it fit into the whole, how does it relate to other pages?
A help page should reflect this.
Bringing this to Drupal 7
Looks like we're moving this way for Drupal 7:
http://drupal.org/node/299050
OpenConcept | Volunteer Canada | prax.ca
--
OpenConcept | Twitter @mgifford | Drupal Security Guide