[drupal-devel] Coding style for admin help: please come to a consensus for the docs team

[Kieran Lal]

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.

    I have 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.  There is also code in the the HTMLarea module  
admin help to check if needed modules are present.

      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