[documentation] A suggestion to improve drupal.org handbooks

[Kieran Lal]

On Jan 22, 2006, at 6:25 AM, Ram Dak wrote:

> Exactly! Having a single document to deal with would bring  
> significant advantages.

We we have currently implemented a single source documentation effort  
for the Administration help pages.   It's been partially successful.   
We update pages in the handbook: http://drupal.org/handbook/modules.   
We have a script that can turn those pages into patches which update  
the help inside the modules.  It took the documentation team about 5  
months to get the scripts written to make this possible, but we did  
it.  It's now kind of broken again.
> With the new workflow options available (?) in 4.7, we could even  
> make this entire process part of a workflow:
>
> 1.) Developers fill in the initial documentation in the project  
> fields provided and it goes into install.txt in CVS and the  
> tarballs. To avoid developer resistance, we could make a minimum  
> set of fields required and the rest, not required.

Sure this is very similar to how the administration help pages are  
written now.  We frequently grab the install, readme, or what ever  
documentation exists.  By the way the documentation is often pretty  
good, just not consistent between modules.  We then morph this  
documentation into the administration help.

I don't think you want to raise the standards for creating a  
project.  For example compare these two lists: http://drupal.org/ 
project/Modules and http://cvs.drupal.org/viewcvs/drupal/ 
contributions/modules/.

There is already a lot of resistance to creating projects because it  
comes with issue queues and requires a higher standard.  There is  
also a LOT of modules in http://cvs.drupal.org/viewcvs/drupal/ 
contributions/sandbox/.  New fields in the project module won't  
hurt.  I think what we want to create is a situation where if  
developers check in their modules that the community and the  
documentation team will show up to HELP DEVELOPERS, NOT BURDEN them.   
We need to create a participatory layer around the project modules to  
demonstrate the untapped value of the Drupal platform.

> 2.) This text then goes to people/volunteers on the docs list who  
> install the modules and document its various intricacies. Then,  
> with access to the same form fields as the developers, they add the  
> extra stuff they have documented.

Ok, but there are already some 400 modules and only 80 of them are  
documented.  So the real bottleneck is not automation but getting  
folks on the docs team to step forward and document a module.
> 3.) Someone (or a set of people if possible, including the  
> developers), reviews the additions and approves them. On approval,  
> the new text gets added to the CVS and module tarballs with the PHP  
> magic you mentioned.

> 4.) Finally, this approved documentation is also automatically  
> added to the drupal.org handbooks

The single sourcing currently comes from http://drupal.org/modules/ 
handbook.  It is going to stay that way.  But we can explore how to  
get text files into the handbook.


> If this makes sense (not too bureaucratic etc.) and is technically  
> feasible,  I will compile all the suggestions people have made till  
> now for a standard format.

Or you could write a module handbook page :-)  Sorry we have about 10  
grand schemes for every contribution that is made right now.  That's  
fantastic that people are so enthused to help.  But the pragmatic  
approach would be to make small incremental improvements to existing  
efforts and then use the momentum from your contributions to improve  
the bureaucracy.

Cheers,
Kieran
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.drupal.org/pipermail/documentation/attachments/20060122/5748d15c/attachment.htm