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

[Kieran Lal]

On May 12, 2005, at 8:04 PM, 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).

Great observation.  Here are some suggestions.

First, there are over 1300 messages in the Drupal docs thread, so if  
you really want to make stuff happen with respect to documentation  
that's the place to do it.

Second, if you are serious then you are going to need a methodology  
and examples for getting that developer documentation written.  Take  
a look at this: http://dev.bryght.com/t/wiki/ 
DrupalDocumentationProcess as an example what many members of the  
docs team are considering as a baseline before contributing to actual  
documentation.

Third, if you do decide to do this then there's a lot of work and  
grunt research that you want to do to make your volunteers  
effective.  Take a look at these tables I put together for the  
documentation sprint I ran last week.
This is Drupal core: http://dev.bryght.com/t/wiki/ 
DrupalAdminHelpDocumentation
This is the 29 contrib modules that ship with CivicSpace: http:// 
dev.bryght.com/t/wiki/DrupalContribsAdminHelpDocumentation

You are also going to want a test site set up running Drupal Head for  
your volunteers.  They are going to be able to use the application as  
they documenting the code to confirm it does what the doc comments  
say it does.

I am pretty focused on admin help right now but I can advise on a  
Drupaldocs sprint if you want.

Cheers,
Kieran