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

[Boris Mann]

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