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

[nathandigriz]

Angie Byron wrote:

> > 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/
>
>
> -- 
> Pending work: http://drupal.org/project/issues/documentation/
> List archives: http://lists.drupal.org/pipermail/documentation/
>
Yes, how do you get a copy of the text to edit?  If you are going to 
create an example to show the new page it looks as though you have to 
start from scratch. This is not very efficient and a pain to cut and 
paste large formatted text form the HTML source. Does this become like a 
wiki when you get the right permissions?

I read the writing style pages and they were lacking some examples but 
not being able to add those examples to show a better structure causes 
me to have to do what I would like to avoid, creating deep linked child 
pages.

There are also some points in the writing manual which I feel are wrong 
and have created problems. One of which is the section on embedded 
headings. Lack of embedding headings adversely effects the readability 
and usability of the text. I could not imagine reading any book without 
some type of  title structure. Embedded headings as an indicator of page 
length is also false. It also goes against BOB for motion impaired 
users. The page should be structured so that a keyboard can be used to 
navigate through the text. Not all of us can use a mouse.

Is there any plan or has there been talk of using a secure wiki?