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

[Gordon Heydon]

Hello,

Thanks for the pointer, but being a developer the biggest beef I have is
the fact the the drupaldoc.org doesn't extend over the contrib modules
as well.

Gordon

Anisa wrote:

> 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.
>>
>>  
>>
>
>
> !DSPAM:4284346d95454551116848!
>