[drupal-docs] Guidelines for error/status messages

[puregin]

Hi all, I'm trying to put together some guidelines
to help module developers write useful, clear, consistent,
friendly status and error messages.  (The messages
generated by drupal_set_message() - these
are the highlighted error/status messages
displayed by Drupal to give the user feedback
about the status of an action, or about errors
which may have occurred.

Please suggest additions/deletions/edits.

Better yet, go to the Bryght Wiki and make
them yourself:

http://dev.bryght.com/t/wiki/DrupalErrorAndStatusMessages

I'm including the initial text here, for your consideration.

Message guidelines

1. Be clear and concise.

    For error messages, give the minimum amount
    of information required to specify the problem, and preferrably a
    solution.  For example, if it's known that a write failed because a
    directory is not writable, give the name of the directory and
    explain that it's not writable - don't just say 'The file could not
    be written.'

    An error message should ideally tell the user:
       What happened,
       Why it happened
       What should be done to correct the problem

2. Use the passive voice:

    Example: use

      The directory %directory has been created.

    rather than

      Created directory %directory.

3. Write complete phrases.

    An article is not necessary, but a (auxiliary) verb must be
    present.


4. 'Could not' vs. 'Can not'.

    Use 'could not' to express impossibility at a moment in the past.
    Use 'can not' to express impossibility regardless of time.  That
    is, use 'could not' to indicate the failure of an action due to
    transient conditions; use 'can not' to indicate the impossibility
    of ever executing such an action.

    Example:

      The file %file could not be written.

    implies that we tried to write the file, but failed.  Perhaps the
    disk was full.

      The alias 'node' can not be used, because it is reserved for
      use by the system.  Please choose a different alias.


5. Use familiar terminology

    Avoid jargon or tech-talk. Use concepts and objects in the domain
    of the user.

6. Tone

    Prefer a formal, courteous, and positive tone.  Avoid words which
    suggest the user was negligent or at fault; e.g., avoid 'must',
    'should', 'wrong', 'incomplete', 'not allowed'.  Address the user
    with 'Please' if an action is required.

    Example:

    Use

      Please enter a title.

    rather than

      A title must be supplied.

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