Club Drupal

The <strong>Advanced help</strong> framework is designed to supplement the Drupal core help system: <code>hook_help()</code>. The goal is to provide a help framework where it is easy for maintainers of modules and themes to create and maintain rich help texts, and for users to access help on the screen.

Unlike the core help system, it allows for help-pages under the “Advanced help”-tab to be structured like an hierarchical book. It also allows pop-ups that provide context sensitive help on demand. By allowing help to be available on demand, the system conforms more naturally to how most people work.

<h2>Advanced help is organized by topic</h2>

With the <code>hook_help()</code> method, help text is organized by URL path. This is fine if you have help text describing how to use a particular project or what a particular project does, but because manuals and documentation are usually grouped by topic, and those topics are determined by the material itself, this format is sometimes limiting.

<strong>Advanced help</strong> allows the documentation author to organize topics as he or she sees fit.  The only restriction is that each individual chunk of text needs to stand on its own as a discrete topic.

Modules and themes can insert their topics into another project's hierarchy, as might be done by projects that extend <strong>Views</strong> or derived themes that extend base themes like <strong>Zen</strong>. Please see the entries for <code>hide</code> and <code>parent</code> in the section “<a href="&topic:advanced_help/ini-file&">Advanced help .ini file format</a>” for details.

<h2>Advanced help topics are processed HTML in their own files</h2>

This separation of documentation from code makes it easy to find and modify help text. Currently, everything is lumped together in <code>hook_help()</code> in PHP strings that are run through <code>t()</code>, and there is a fair amount of PHP code necessary in this system that actually gets in the way of writing good, explanatory text.

In fact, requiring a documentation author to understand PHP at all is a detriment. The idea that documentation writers need to have PHP development as a skill seriously reduces the number of available contributors. HTML, on the other hand, is a much more common skill, is relatively easy to learn, and the amount of HTML needed to write documentation is only a little bit more than the HTML used in forum posts.

Another benefit from not using PHP is that the HTML-files themselves are safe. They are filtered to escape malicious script code that could take over the server or do worse things.

<h2>Advanced help files are translated as a file</h2>

It is actually not easy to translate documents as strings, particularly when the language being used is very much unlike English. In fact, when translating a document, the organization of the sentences may change drastically. It is also a burden on the CPU to do this, as you are indexing on very long strings.

Translators have a much better time translating a document as a unit, because of the presence of the entire context.

<h2>Advanced help has its own navigation system</h2>

By making use of a navigation system specified in a .ini file (which is not PHP code and therefore safe to use), the help can be structured like a book, which is typical of online manuals. This is familiar to users, can be organized (and re-organized) and allows a module or theme to include significantly richer text without burdening the PHP code with having its help loaded unnecessarily.

This book can be navigated hierarchically as well, making it easy to keep related topics together.

<h2>Advanced help is indexed by the search engine</h2>

An important goal of this system was to add searchability to the help. By being able to enter keywords into the search box and find relevant topics, we come up with a system that resembles the kind of help that comes with many operating systems. This is very valuable when searching through manuals trying to find out how to do a particular thing.

This search is specific to the help, meaning that the help will not be mixed in with the global node search. This can be considered both an advantage and a disadvantage. For the most part, this help system is meant to provide help to site administrators, and content searches should not find it. The disadvantage, of course, is when you want to use it for end user help, you will not be able to.

<h2>Inline help can be brought in via popups</h2>

In addition to the manual-like hierarchical navigation, <strong>Advanced help</strong> can also provide context-sensitive additional help through a popup. While popups are controversial, the argument for using them is that when getting help while on a form, <em>a popup will not throw away a user's data.</em> Browsers are not very friendly to input forms if they are not submitted, and navigating away from the form can be dangerous. There are various other solutions to this problem, but each one has a drawback. The drawbacks to popups are well known, but mostly it is the irritation of having new windows. When getting help, though, a popup is usually invited. Help should not interfere with what the operation the user is trying to complete. It differs greatly from the uninvited popup, which are usually ads or popups meant to prevent users from navigating away from a site.