[drupal-devel] Coding style for admin help: admin/help#modulename

[puregin]

Hello,

    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 
inconsistent.

    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 
entirely.

    Kieran has created a table of 61 modules and samples of the many 
different styles of coding (see below [1]).  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.

      Djun / Kieran

[1] Table of Admin help samples: 
http://civicspacelabs.org/home/node/12711

Useful links:
   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/handbook/modules/modulename



--
Djun M. Kim, Director                           
djun.kim at cielosystems.com
Cielo Systems Inc.                              
http://www.cielosystems.com
Strategic Software Research                     Tel:   (604) 739-3941
302 - 1298 10th Avenue West                     FAX:   (604) 739-3943
Vancouver, BC, V6H 1J4                          Mobile:(778) 895-1379