[drupal-devel] Coding style for admin help: please come to a
consensus for the docs team
kieran at civicspacelabs.org
Tue May 31 00:42:49 UTC 2005
In response to a user survey of documentation needs, the Drupal
documentation team is working on writing consistent and usable admin
help documentation for core and contributed modules.
We are maintaining this documentation in the Drupal handbook, as
a single source for built-in and on-line help documentation. Each
core and contributed module will have an executive summary section in
the handbook. This text will also be interpolated into the _help
hook of each module as the admin help text.
Current admin help text and older handbook module pages will be
accessible from this executive summary.
The benefits are:
1) consistent and usable documentation.
2) a single source for documentation, which will be the handbook.
We are currently trying to automate the process of interpolating
the admin help from the handbook on Drupal.org
into the module code.
Unfortunately, the coding style around the _help hook is quite
It would be appreciated if the Drupal development community could
come to some consensus so that the documentation team can easily
create a large number of patches in a reasonably automated way.
Improvements here will also likely help with extraction of text
for translation, and with eventually removing hardcoded text from the
I have created a table of 61 modules and samples of the many
different styles of coding (see below ). For example, in the
core modules, node.module and user.module both use PHP to dynamically
create content. Some but not all of the core modules use the second
parameter to t() for formating URLs. He has extracted samples of
the admin help from 30 contributed modules. The code is not exact
but should give you a flavor of the inconsistency, including the use
of theme calls, in location.module, and multitple t() calls for a
single piece of text. There is also code in the the HTMLarea module
admin help to check if needed modules are present.
Djun / Kieran
 Table of Admin help samples: http://civicspacelabs.org/home/node/
Core modules: http://drupal.org/handbook/modules
Contributed modules: http://drupal.org/handbook/modules/contributions
Executive summaries of modules are now at: http://drupal.org/
More information about the drupal-devel