Help API

...in no particular order. Much of this is stuff I've heard others discuss, along with my own ideas after watching the U of M Usability presentation:

• Help text positioning - consider whether current "above the fold" text could be better served in another location on the page. On the development list, for instance, Gabor raised -- in passing -- the idea that perhaps help text should be displayed as a block located by default in content top. This would have the added benefit of being moving it over to the sidebar, etc. Currently, of course, help text -- especially on pages like /admin/build/modules -- takes up much too much space.
• Conditional display - Also -- for the sake of argument -- if help text were displayed as a block, it would automatically gain: a) the ability to only be displayed for some roles, b) the ability for advanced users to turn it off (conditional block display by user), c) the ability to only be displayed when a certain bit of PHP evaluates true (for instance, do not display help if system_compact_mode() is TRUE).
• Reduce reliance on "modularity" - just as we have different views of /admin, we should retain our current "by module" view of /admin/help but create a topical set of embedded help texts that we use as the default. "How to create new types of posts" or "How to enable comments on my posts", etc.
• Glossary - build in a cross-referenced glossary of definitions and related concepts.
• Enhanced linking to d.o. - create a more finely-grained system of cross-references between the embedded help and the online handbooks.
• Sexy it up - a little styling on help text, along with some appropriate graphics and icons would go a long way. Use jQuery to hide or show help text depending on the user's needs.
• Context-sensitive - we should do more of this than we do. An icon in hard to understand FAPI descriptions that retrieves a longer explanation and examples in a way that doesn't destroy the page data (by navigating away), for instance.
• De-jargonify - We've made progress here, but there is still a long way to go.
• Creative UI - Use our existing interface in creative ways. There are some ongoing experimental patches using jQuery to create in-field "hints", etc. Even not-quite-as-creative tooltips could help.
• Increase consistency - We've made improvements in consistency, but still have much to do. I really think that terms like "node" are not that problematic as long as we use them consistently, appropriately and with the right definitions.
• Dynamic content - As mentioned above, delivering embedded help through something like l10n_server would be nice, but presents some problems in terms of providing translations. Like plans for strings translated through the l10n_server, it would be nice to get feedback from users in the field when a help text snippet is difficult to understand.

Here's another idea. Don't include help at all, but write a framework so help can be dynamically grabbed from drupal.org. This could be done through xml, similar to update status; the results could be cached, so this would not be so expensive on each page load.

Hi,

you all have great ideas and to sum it up I would recommend to have a look at the Eclipse IDE Help System.

Eclipse IDE lives by it's massive eco system of plugins just as Drupal does. And while their system is much larger and even more complex than Drupal they are/were facing the same problems. So over the years they came up with a very nice and rich featured help system.

One feature I liked from the start are the so called "Cheat Sheets". Think of them like inline help for modules (Eclipse plugins) presented in a collapsible block. What they do inside Eclipse is to guide new users when adding a new project, set up your cvs connection, helping you build your software project, displaying help files or just links to resources. Cheat sheets do this in a very intuitive way. They can act like a step by step quide, they can present context sensitive information (help, tips and tricks, getting started), and they link to internal and external references and resources.

So in the Drupalverse we could provide "Drupal Cheat Sheets" that help users set up Drupal step by step like in a wizard. Or think of adding a guided tour presenting all the relevant sections of Drupal. With the help of jQuery this can be a rich user experience.

As an real world example, I would love to see such a module when entering content with a filter like textile or markdown. Most of my clients like textile but they are constantly asking for help how to create certain styles. Adding information about the textile syntax in a sidebar Drupal Cheat Sheet could be a consistent place for all kinds of filter (insert_block, insert_view, insert_node, etc.) syntax information.
Another area where Drupal Cheat Sheets could be handy is when you set up a module. Think of modules that present multiple lines of "help text" under each input field just to tell you that this input requires a certain format or is restricted 140 characters. Such information could be put into the cheat sheet block and displayed on focus.

I'm not that much into Drupal programming so far, but I guess it would be helpful to provide a hook_cheatsheet that allowes programmers to display help information for modules in a generic cheat sheet block? Another important fact is, the system is already invented, tested, used by millions of developers and based on XML. So it could be easier to implement.

This was one idea for a better help system in Drupal. I think there are tons of software solutions which dealt with the same problems Drupal has. And maybe we should have a look at how they solved it so that we can come up with a superb solution for Drupal 7+!

With best regards

Mike

Check out the google adwords learning center.

http://www.google.com/adwords/learningcenter/

I think it's a great model for a help system.

As I mentioned above, I think "flows" is a good alternative to wizards. It points the user in the right direction, without holding their hand. This will prove beneficial when they move into performing the task without help.

I had a discussion recently with someone about a program which was extremely daunting at first, but included some basic tutorials at the beginning. After watching a couple of those, he immediately felt much more comfortable in the environment, and could find things quicker; ultimately, he kept using the program.

I feel like we should do that for Drupal ;)

I just posted this issue http://groups.drupal.org/node/9842

Maybe it's something that could be done/incorporated as part of this?

Staring with some of the things here and some thinking and discussion here's a proposed proposal for a coding project:

Drupal's help system is fairly incomplete. At drupalcon there were many examples where the lack of a help system contributed to its usability woes. This project aims to enhance Drupal's help system through a pluggable, extensible help system API.

Drupal Help should:

• Provide help for any Drupal path by adding a suffix to the path (perhaps /help)
• Identify a "provider" site for help documentation... defaulting to drupal.org
• Provide a server implementation for serving help documents based on the area for which help is being requested.. this should query down the Drupal path using a system like the theme system where modules can override the response or pass it along if they have no response
• Provide a glossary functionality where key terms can be identified and automatically linked in help text
• Be configurable but come with simple defaults
• Cache help system locally on either a "grab x help items per cron run" or cache item on request depending upon local setting
• Add links to help throughout Drupal where it makes sense (i.e. help links for each item on the various administrative pages
• Provide for delivery of help videos, wizards, flows
• Provide for help along side content it pertains to
• Provide a framework for accessing help documents in a task-centric manner (may be the same help as the context-centric general model with a different outline)

Difficulty: Medium

Mentors: SIGN UP HERE

--
Blog: Adding Understanding | Drupal Developer Search | Drupal Services: Brauer Ranch