Improve the Help system in Drupal

Enabling users to get inline help, with reference to in-depth topics, Drupal-centric terminology help using tooltips(glossary), potentially leading users from error or warning messages into the contextual documentation and a whole new experience browsing help topics in administration, is a part of usability improvements to Drupal.

Separate help file for modules, ease of maintenance of help by other contributors, etc. are some of the features benefiting Drupal module developers.

Project page — http://drupal.org/project/help_soc (Abstract)

Demo installation — http://soc08.myzonelabs.com/

Discussion Group — http://groups.drupal.org/help-system

⁣

1. Release notes

1.1. 7.x-0.1ALPHA1

This is the first release of the help module for Drupal 7 incorporating most features of advanced help module with some minor changes.

Installation:

1. Before installing Drupal 7(HEAD release), remove the help module at modules/help.
2. Place the help_soc package under sites/all/modules directory
3. Install Drupal. Help module is installed automatically.
4. Enable Help Example module. UPDATE: Oops, looks like I forgot to commit help_example.
5. Installation complete.

Change Log:

• Change of path for help topics.
• Change in breadcrumb links.
• Back and Close links in popup help.
• Theme popup view only when topic is opened in a popup(javascript), aka Degradable.
• Bind click event to help links to open in popup, using jQuery.

Known caveats:

• Current help text cannot be browsed under admin/help.
• Hence, all the "More help" links are currently broken.
• Broken RTL CSS.

1.2. 7.x-0.2

Change Log:

• Help Example now included in package. Provides links to working examples of new help feature.
• Working example links at admin/build/modules and admin/settings/site-information pages.
• Added #help form element, to link to help content, inline with form fields(text field, etc.).
• Improved theme_help_link().
• Removed Back and Close links from popup, in favor of breadcrumbs and browser close button(X).
• TOC(Table of contents) on index page are not listed recursively.
• TOC shown on each page, with the current or parent topic expanded, and others collapsed. Note: Broken for deep children.
• CSS styling for TOC and children TOC(below topics), for better visibility.

Known caveats:

• Table of content doesn't "expand" menu when browsing topics with depth greater than 1. Current code is mere hackish approach.

1.3. 7.x-0.3 (Prospective)

Change Log:

• Browse help "By Modules".
• A bit styling for Table of contents box and on by-module browsing in popup.
• Integrated hook_help() and hook_menu().
• Help SoC module now overrides Drupal's default help system to provide inline help on pages. What is drupal_help_arg() all about?
• if module_name/help/about.html exists, it'll be defined automatically, and can be overridden in module_name.help.ini.

2. Weekly reports

2.1 Week 1 ~ 2008-06-18

1. What did you get done this week?
   Better looking wiki page(not a necessary task though), The porting was quicker than I thought, and that combined with a few changes listed in change log, formed the first release 7.x-0.1ALPHA1 (rocket science naming, won't be repeated.).

2. What's your plan for next week?
   Spend more time, coding and thinking. I'm looking for inspirations and suggestions all the way!

3. Is there anything holding you up?
   You mean distractions? A lots.

2.2 Week 2 ~ 2008-06-24

1. What did you get done this week?
   Mostly tweaked the pop-up UI, added new form field to handle inline help link, and the upcoming release or the current dev. release includes help_example module that missed to make it into the first release.

2. What's your plan for next week?
   Wrap up the pop-up improvements and move on to writing some quick help for a few modules, and based on them, start with help UI in administration (admin/help; by-module, by-topic, etc.).

3. Is there anything holding you up?
   A month's training starts at my institute, eating my afternoon on weekdays. No more late nights. But kind of good at early to bed, early to rise... principle :D

2.3 Week 3 ~ 2008-07-02

1. What did you get done this week?
   The majority of changes this week affected how the help is defined by module developers. Drupal's core hook_help() has been integrated with hook_help() to provide inline help using the new module package. Moreover, if help/about.html file is present, whether there is a example.help file or not, it'll be automatically assigned to be the default help page for that module, unless overridden.

2. What's your plan for next week?
   Allow modules to override or add some new help into other module. It might be tricky to retain it's compliance with current translation approach. Other than this, this week might strike for some more UI and features, hopefully including the glossary/dictionary!

3. Is there anything holding you up?
   Nothing much.. But uhmm, python learning eagerness? I have been working on a python script(my first): g15-gmail-notifier, if you know what G15 is, you know what it means. :)

3. Self notes:

1. Make it easier for module developers to add help
   1. Move defining of help topics into .info files, or into maybe hook_help() with syntax similar to hook_menu(). Both .info and hook_help() have been implemented(currently commented) but none of them proved to be as efficient as the current method. @see http://www.pastie.org/224271
   2. A default page, say about could possibly be a default help file, and could be loaded without the need of parsing help ini.
   3. Help SoC package does not provide support for inline help, viz currently provided by hook_help().
   4. Integrate hook_help() with hook_menu(). e.g. http://www.pastie.org/224158
   5. Instead of aggregating topics from a help server, a special module could be provided to override and include a lot of help on general topics. Different modules for this could exist based on the level of expertise of the administrator.
   6. Should we allow end-users(not the admins) to browse help? In other words, separate help permission from 'administer site configuration' permission. [Might not happen]
   7. example.help instead of example.help.ini
   8. Separate the help contents from module/hook_help().
   9. Translatable help text. (not well tested, nor upto drupal standards).
2. Make it easier for people to use help
   1. Glossary for drupal terminology.
   2. Route users from errors and warnings to help topics, like "What to do in case of a MySQL error?" or just link to "Troubleshooting".
   3. Ability to search through help topics. If caching or other such features get into module later on, search system will need a touch most of the time. So this one is postponed for later work.
   4. Bottom navigation should link to child pages too(nested), similar to book module.
   5. A "Welcome to Help center" kind of Help page with aggregated topics. Something on the lines of this.
   6. Make users able to browse help content based on their "topic", independent of modules. (as opposed to current per module topics). [Might not happen]
   7. Link to help on modules page for disabled modules. This would require a core patch, although a hackish approach could be attempted in help soc package.
   8. Browse help topics defined by each module. A page similar to admin/by-module.
   9. Present "flexible" help links next to form fields.
   10. Help links on modules page. Currently accomplished as a mere demo. Requires core patching, or just some hook_form_alter() work.
   11. Display "Table of contents" on all help topic pages.
   12. Optionally, launch help topics in popup, when not on help portal. Provides better experience, as the user doesn't need to leave the page where they might have filled up certain fields, which possibly could be lost when navigating back to that page.