[drupal-docs] Module pages

[Anisa]

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?

Anisa.

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