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

[Anisa]

There is a place now in the new handbook for contributed module 
information.  :)

To contribute, use the docs list.

Anisa.

Gordon Heydon wrote:

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