[documentation] the documentation site is too broken and lacks formatting and writing style

[Angie Byron]

 > I guess I will have to file issues first because a lot of fixing this
 > requires that you move infomation and destroy the old page which
 > probably means having administration previleges right?

True, actually executing the changes requires administration privileges to pull 
handbook items out of moderation. But anyone can go to:

http://drupal.org/node/[whatever]/edit

and submit changes, which will then go to the moderation queue (see: 
http://drupal.org/handbook/updates).

You can also create new book pages from:

http://drupal.org/node/add/book

This is useful if you wish to show us a "before and after" of what a page would 
look like. Then an administrator can apply those changes to the original page if 
all looks good.

And finally, once you've proven yourself as a contributor, you can apply to 
become a "Site Maintainer" (see: http://drupal.org/site-maintainers) so you can 
do these changes yourself. Though any major handbook chages should still 
generally go to community review first, via this docs list.

 > There is also a breaking up up of information because although the 
configuration is on a single page in Drupal, the instructions are broken up into 
9 lead pages and dozens of child pages. This is unnecessary and creates more 
confusion while putting a stop to the short term attention span of the user.

Just be careful to strike a balance between deep-linking and making 60,000 word 
pages that no one will read because they're too dense with information. There is 
something to be said for wanting specific information and being able to go 
directly to it, rather than having to scroll down 10 pages of text to find it.

 > Furthermore I think that there whould be a handbook page that shows the right 
writing format and style to be used in the handbook.

There is actually a whole section in the documentation handbook about this. See: 
http://drupal.org/documentation-writers-guide

Thanks for offering to help!
-Angie

nathandigriz wrote:
> Bèr Kessels wrote:
> 
>> Op woensdag 11 januari 2006 12:51, schreef nathandigriz:
>>  
>>
>>> In conclusion:
>>> Furthermore I think that there whould be a handbook page that shows the
>>> right writing format and style to be used in the handbook. There does
>>> not seem to be anything wrong with the handbook information. There is
>>> lots of it and it is useful. The problem is in how it is being
>>> delivered. To repeat in a different manner: There are too many short
>>> paragraphs on different pages that give no information on the task at
>>> hand. They are only serving to deep link the handbook.
>>>   
>>
>>
>> In Drupal we have a sort of 'just do it' mentality. Your ideas sound 
>> good. So please apply for a role so that you can change the texts. You 
>> can aslo file detailed issues against any documentation.
>> Bèr
>>  
>>
> -- 
> Pending work: http://drupal.org/project/issues/documentation/
> List archives: http://lists.drupal.org/pipermail/documentation/