Let’s start with a moment of nostalgia... Think back (way back for some of us), to when you installed or worked with your very first Drupal site and wondered what all those modules did. Book? Node? Trigger? How mystified you may have been reading down the list of modules on the Modules administration page or in the modules directory. Recall when you installed a new contributed module and wanted an overview of what you could do with it, but there was no documentation online. Then the moment where you thought: isn’t there some kind of guide for this?

There is indeed a built-in general guide within each Drupal site. This most basic information about each module can be found right within the install in the administration area, thanks to the Help system (supported by the Help module). The Help module allows developers to include both contextual help and also a per-module help page. This text is shown to site administrators (and other developers) to help them configure modules, administer their sites, and explain the functionality of each module.

Every core module in Drupal 7 has a standardized help page that provides some basic information and links to the module’s online documentation landing page. You may not have known about this because the content was inconsistent and sometimes very brief in Drupal 6; in Drupal 7, the content has been fully rewritten for each module and is now a lot more helpful. Contributed modules can also be updated to follow this same standard so they provide consistent and effective help to site administrators within their Drupal install, as well as pointing users to the online documentation.

The new Help standard in Drupal 7

The Help module and its related functions haven’t changed in any substantially technical way between Drupal 6 and 7; the main change is that the text in each module’s help hook has been updated and reformatted to follow a standardized structure. (The small bits of contextual help that some modules also contain did not undergo any major changes.) The updated text now gives a general overview of functionality, links to appropriate administration pages within the Drupal install, and links out to the online documentation for the module on Drupal.org.

The Help content can be accessed through the main “Help” link on the new administrative Toolbar (which displays when the core Toolbar module is enabled) or at http://example.com/admin/help. Each module’s help page can also be accessed via the “Help” link next to its name in the Modules administration page (through the “Modules” link in the Toolbar or at http://example.com/admin/modules).

The new Help standard was designed to provide a more complete overview of each module’s functionality and administrative options. It is geared toward informing site administrators or new developers about the basics and to lead them to the more detailed online documentation at Drupal.org. Each Help page should include:

- A brief “About” section reviewing what the module’s purpose is. The end of the About section should end with “For more information, see the online handbook entry for [Module-name module].” where the module’s name links to the online documentation landing page for that module.

Built-in vs. online

You might be wondering why we insist on keeping the core help pages so brief. Aside from the Help system only supporting a single page per module, the main reason we want to keep the bulk of the information on Drupal.org is that it can be modified easily and at any time during the development cycle. Because of the requisite string freeze for core text, which allows Drupal to be translated into many languages, the text cannot be changed between versions.

When it comes to contributed modules, the priorities are slightly different. It's important to stay up-to-date with the potentially large changes in functionality from one minor version to the next, and because string freeze doesn't apply here it's fine for the built-in help text to be updated anytime. It may well be more efficient to keep the help text directly in the module code (in the built-in help or using Advanced Help module).

The drawback with this approach is that non-developers cannot easily update the text (which may or may not be desirable by a given maintainer). Keeping the bulk of the detailed documentation online allows the information to be freely updated by Drupal.org users and Documentation Team members without having to write core patches.

It's obvious by the mishmash of approaches that there is no single most effective method that works for both core and contributed modules. When built-in help and online documentation are used extensively, it takes extra work to keep the two in sync. Some small, targeted improvements to Drupal.org's documentation infrastructure could assist in creating a system that would work for core and contributed modules alike.

- A “Uses” section which briefly covers the main functionality of the module, such as what content types, administrative options, and permissions the module creates. For more complicated modules, this will have more sections, but each section should be kept at an overview level with the bulk of the detail in the online documentation.

At present, most contributed modules do not follow the help standard that was created for core, but if you would like to update your module to follow this consistent standard, there is an easy-to-follow template at http://drupal.org/node/632280, You can also support Drupal end-users and developers by helping maintain the API documentation for http://api.drupal.org.

Consistent URLs

The URLs for the built-in Help and online documentation pages should all be consistent ̶ this will help if we need to automate any process in the future and also lets you easily find documentation by URL. Using the File module, for example, the module’s filename is the base for all related URLs:

• Built-in help page: http://example.com/admin/help/file
• Online documentation: http://drupal.org/documentation/modules/file

For contributed modules, the URLs should be consistent with the module’s project page on Drupal.org. For Pathauto, which uses the project path of “pathauto”, we have:

• Pathauto project page: http://drupal.org/project/pathauto
• Pathauto built-in help page: http://example.com/admin/help/pathauto
• Pathauto online documentation: http://drupal.org/documentation/modules/pathauto

Issues to address in Drupal 8

Despite the help system now having improved content, there are still some major issues with Drupal’s Help system that need addressing in Drupal 8. The most pressing issue in terms of serving our end-users is whether we can agree on using this standard consistently across core and contributed modules. Currently, only the core modules’ help content follows the standard and has relatively extensive online documentation. When we look at contributed modules, the amount, structure, and quality of documentation varies a lot. Issues we’ll need to consider in evaluating how to make Help even more consistent and effective include:

The built-in Help pages can only be updated via patches/code.
Because it's in code, the help text for Drupal core is governed by string freeze and can’t be updated later on, forcing the bulk of the content to remain on Drupal.org. This is good in regards to more open collaboration, but may not be as efficient for contributed modules (if we want a consistent method).

Documentation on Drupal.org and in code have to be written and maintained separately (which risks them becoming out of sync, and requires more work to maintain).
Built-in help pages are currently constrained to a single page per module.
There are other methods of offering help content. “Advanced help” (http://drupal.org/project/advanced_help) is being used for some contributed modules, which is inconsistent (many end-users don’t even know it exists!) and tends to mean the online documentation is not always up-to-date.

References

• Working with the Help system: http://drupal.org/documentation/modules/help
• Help text standard (for core and contributed modules): http://drupal.org/node/632280
• Help hook (API): http://api.drupal.org/api/drupal/modules--help--help.api.php/function/ho...
• More information about the Drupal 7 Help text standardization: http://affinitybridge.com/blog/story-drupal-7-core-help-update
• Want to work on Help? Join the Documentation Team http://drupal.org/contribute/documentation/join or follow the Drupal 8 issue http://drupal.org/node/1031972