[documentation] Re: documentation Digest, Vol 14, Issue 61

[Chris Johnson]

Boris Mann wrote:

> Please...let's not go down this road right now, unless there is someone 
> immediately standing up with the time and resources to do this right, 
> which likely means integrating it into project module itself in some way.
> 
> Myself and others are going through editing the project pages and 
> linking the documentation field that is already there to the individual 
> http://drupal.org/handbook/modules pages. There is a format for that, 
> and it tries to cover as much of the mentioned items as possible. Please 
> pitch in and help update.
> 
> It sounds like additional documentation around very basic module 
> installation steps is needed. Please review the "Installing new modules" 
> page and suggest changes: http://drupal.org/node/17473 -- you are always 
> reading the INSTALL.txt file and suggesting bug reports against it for 
> bug fixes, right? :P

I always read all of the *.txt files for a module before installing it. 
Unfortunately, module authors are widely random on what information (if any) 
they put in each of those files.  Sometimes there is something useful there, 
but often it's not.  I occasionally do write bug reports for such things, but 
not very often, since I'm already burning through time I don't have trying to 
figure out what a module really does and whether it will be useful.

I'd like to see more of the onus of good module documentation forced on the 
module authors.  I'd prefer modules not even show up on drupal.org or for 
download until reasonable documentation is supplied.  I know the old saw is 
that programmers don't like to write documentation, but there really is no 
excuse.  Anybody can learn to write adequate, useful information about a module.

I +1'd Gunnar's extension of Ramdak's posting because it seemed like Ramdak 
was willing to do the work.  :-)

Whatever method is used to improve module documentation, I'll be in favor of it.

..chris