[drupal-docs] Module pages

[Kieran Lal]

On Jun 5, 2005, at 8:41 AM, Anisa wrote:

> Alright.  This is completely mukatsuku.  And thus this mail is a  
> bit of a rant, but forgive, please.
>
> How is the documentation we are making now better than what was  
> there before?  The point was not only to update the documentation,  
> not only to reorganize it, but to make it better.  You can't say  
> it's better because you made something that wasn't there before.
>
> A paragraph, for example, should be used more sparingly.  It's  
> something for expanding on a main topic, not a string of disparate  
> sentences.  If you can put the sentences in a bulleted list without  
> making any changes, you've abused a paragraph and made something  
> harder to read unnecessarily.
>
> By making the top most page about the module the source for the  
> admin help, aren't you tieing your hands behind your back?  Keeping  
> the 'executive summary' the same is one thing, but is the admin  
> help really the most useful thing there?  Just because it is  
> conveinant for us to have one source for both does not make it  
> conveinant for the user.
>
> When I asked Kieran about some of this (using, I hope, softer  
> language ;), he said that as comments come in, the pages will  
> evolve.  Well, there are a helluva lot of pages there, and there  
> needs to be some discussion on what's a good format for these  
> pages, what information do we want them to contain, not just on the  
> main page, but in the child pages. It's hardly practical to make  
> changes one by one.
>
> So, I have two questions.  1) Is it really a good idea to make the  
> admin help the first page a user sees when reading about a module,  
> and, if so, how can we make it better?  2) What information does  
> every module need to have?  For example, do you want to include  
> information about the permissions, the blocks that are made, etc?

Here are the authoring guidelines for administration help.   I would  
suggest people comment here: http://drupal.org/node/24268 about the  
guidelines, or comment on the list.

As for the constant evolution of the pages, this seems to be working,  
although I agree it is not efficient.  There are several efforts  
going on here and we have to recognize that tackling 60 or more  
module pages is impractical for everyone except me.  Let me explain  
the 7 major efforts that are ongoing and how those efforts have made  
it impractical to come up with a single template that is applied  
once.   The first effort is to get actual end users, not developers,   
to test all 60 modules for the 0.8.1 CivicSpace release.   These  
motivated testers overwhelmingly complained that the lack of  
documentation made it too difficult to do any testing as they could  
not understand how to use the modules.   The second effort was to  
write documentation in response to the results of the documentation  
survey which indicated the most needed documentation was module  
documentation.   The third effort was to improve the usability of the  
administration help documentation by making it scannable, and  
including links to relevant pages to help improve the ability to  
include tasks and reduce errors in task completion.   The forth  
effort was suggested by Charlie, the documentation coordinator, to  
single source all documentation in the handbook by making  
administration help the module executive summary pages.   The fifth  
effort was to create an automated way to extract the documentation  
from the handbook and format it so that it wasn't so onerous for the  
documentation team to update the administration help for all  
contributed modules in the future.   I have been writing scripts and  
prototyping with Djun to do this.   The sixth effort has been lead by  
Djun to write updates to the book module so that pages could be  
extracted and imported into Drupal.  The seventh effort has been to  
implement a re-organization and re-write of the Drupal documentation  
handbooks into 5 main handbooks as a suggested by Dries and as proven  
viable by my usability sorting experiment with around 60 participants.

So the criticism is completely expected, and welcomed.  However, any  
hope that those 7 efforts would have been possible to be coordinated  
in advance so that it could have been implemented efficiently once  
are just not realistic.  This community lends itself to criticizing  
something, rather than agreeing in advance unanimously how and who  
will implement it.  However, now that we have a documentation  
coordinator in place it is more likely that this coordination could  
occur for future efforts.

Thanks for your valuable critique.

Cheers,
Kieran

>
> Anisa.
>
> -- 
> [ drupal-docs | http://lists.drupal.org/listinfo/drupal-docs ]
>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://drupal3.drupal.org/pipermail/documentation/attachments/20050605/03bf9c9f/attachment.htm