[drupal-devel] Coding style for admin help:
puregin at puregin.org
Mon May 30 20:40:03 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 code
Kieran has 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
Djun / Kieran
 Table of Admin help samples:
Core modules: http://drupal.org/handbook/modules
Contributed modules: http://drupal.org/handbook/modules/contributions
Executive summaries of modules are now at:
Djun M. Kim, Director
djun.kim at cielosystems.com
Cielo Systems Inc.
Strategic Software Research Tel: (604) 739-3941
302 - 1298 10th Avenue West FAX: (604) 739-3943
Vancouver, BC, V6H 1J4 Mobile:(778) 895-1379
More information about the drupal-devel