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/(Out of date)

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.
• Added search for help topics. Available at ?q=search/help when search.module is enabled.

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. :)
   UPDATE:
   #1 6 to 8 hours of electricity/power cuts during day in our region :(
   #2 Need to submit a short project report at my university.

2.4 Week 4 ~ 2008-07-15

1. What did you get done this week?
   Updating soon...
2. What's your plan for next week?
   Updating soon...
3. Is there anything holding you up?
   9am to 11pm power cuts, with half an hour available twice in between. This doesn't mean I want to excuse myself to work on the project. But this is yet another excuse from me.. sorry dmitrig01 :( With the little time we get to browse in the morning, I am just able to cope up with updates all around and have a peak at what is going on. During power off time, I am able to make check my mail or browse around using wireless internet on my psp, but not enough for development. This might go good if I turn nocturnal. And we are considering buying a generator, as my project isn't the only one being affected.

2.5 Week 4 ~ 2008-07-15

1. Going off for little over a week for a meet at Google's office, couple of thousands kilometers from here.

2.6 Week x ~ 2008-08-15

1. A lot of changes went into the module to be compatible with current drupal core. Moreover, we now have help module's help as the special "help topics" container. In other words, help.module's help shall contain all the table of contents or topic listings, which link to individual module's help. about.html file was added for each core module, with a mere description text in it. Other changes include about page being the default page for a module. i.e. if you visit admin/help/color, it'll be same as admin/help/color/about.

   As the TestingParty08 issues end in drupal's IQ(issue queue), expect HelpParty08 ones. Each module needs documentation of the features and configuration that it provides.

   Also worth nothing here: yoroy's suggested welcome page layout: http://www.yoroy.com/elders/drupal/help-startpage.png

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. [Not soon]
   6. Should we allow end-users(not the admins) to browse help? In other words, separate help permission from 'administer site configuration' permission. Feature added, but broken due to parent path permissions. Expect rollback soon.
   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 of Drupal terminology. I'll make it, however would miss SoC deadline.
   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".[Will not happen]
   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. [Welcome page structure is in. Now to the layout and content part. This will likely be the welcome to Drupal page as well.]
   6. Make users able to browse help content based on their "topic", independent of modules. (as opposed to current per module topics). [Will not happen, We have a better proposal; see Welcome page post.]
   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. [Will not happen, makes less sense to provide help for modules that are not enabled.]
   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.