[drupal-devel] A little about my morning. - Rant on Documentation

[Gordon Heydon]

Hello,

I had a fun morning. When I got up this morning I had an email from a
client with a problem with the ecommerce module which was not sending
out the email alerts to customers. In the end it turned out to be a
problem with the payment gateway that I had developed for him. So here I
am investigating/programming and fixing his problem before I could leave
to go to another client, so doing some creative thinking and find the
solution as fast as possible.

This got me to thinking, and the main reason that this problem occured
in the first place. Basically the problem was that "Documentation for
contributed modules sux" (I am not singling out the ecommerce module,
AFAIK it all sux).

Basically I feel the problem is that there is no place for
development/user/admin documention on drupal.org/drupaldoc.org for any
of the docuementation that relates to the contributed modules. If there
was something like this then the fact that the payment gateway module is
required to call the functions to send the emails and may not have been
making up a solution to a problem that I didn't know about on the fly.

For a start I think that it would be good to have drupaldoc.org include
all the documentation from the contributed modules. I know that a lot do
not have the the phpdoc comments (I know that mine do not, but I would
fix this if it is going to be used).

Then maybe adding sections to the user and admin sections of the
handbook so that the contributed modules can build documentation. This
also means that people who cannot program or contrbute modules can
contribute  by writing documentation much like we do now for the core
documentation.

Just my thoughts.
Gordon.