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

[nathandigriz]

Boris Mann wrote:

>
> On 11-Jan-06, at 10:44 PM, puregin wrote:
>
>> On 11-Jan-2006, at 6:44 PM, Charlie Lowe wrote:
>>
>>>
>>> nathandigriz wrote:
>>>
>>>> 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.
>>>
>>
>>     Embedded headings are an issue
>> of authorship and editorship, not readership.
>> They neither add to nor detract from
>> readability and usability.  A heading is a
>> heading as far as a reader is concerned.
>
>
> Since Djun came >< this close to becoming documentation czar, I'm  
> inclined to put my vote his way for all the reasons he quoted. Edit a  
> Word document in outline mode sometime, and you'll see what a pain it  
> is if you don't match styles with headings -- each section SHOULD be  
> a node, otherwise it is incorrectly structured and needs to be  
> consolidated or expanded.
>
> Djun, maybe getting people the handbook in OPML/outline format would  
> help in re-organizing on the desktop, since they could fiddle with it  
> locally and propose changes more easily....
>
> -- 
> Boris Mann
> Vancouver 778-896-2747 San Francisco 415-367-3595
> SKYPE borismann
> http://www.bryght.com
>
> -- 
> Pending work: http://drupal.org/project/issues/documentation/
> List archives: http://lists.drupal.org/pipermail/documentation/
>
I am sorry but I still disagree. My experience comes from a newspaper 
journalist view and having had to to help with editing. Typographic, 
layout, headers and print structure are the most important thing from a 
readers point of view. Many a newspaper have gone under and many text 
books fail because of the lack of proper structure. this is one of the 
problems with online reading. Many times the time proven methods for 
making reading a document easy and interesting are overlooked in favor 
of software workflows and the capability of shortening a work routine. 
As proof of the point you could ask yourself how all this information 
would look if you had to put it in paperback form. How would you 
structure a PDF book? You could not very well set seperate  sections for 
every paragraph. Logically the only way would be to find a basic 
structure that work and stick to it. Sticking to the basics is more 
important and will get less complaints form the readership than trying 
to make things easy. As someone mentioned, this is hard work. It is 
lengthy, painstaking and monotnous but the job just seems to get bigger 
when you try and circumvent the tasks by changing proven ground rules.