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

[Charlie Lowe]

puregin 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.

Incorrect. Headings are often used within a page to make a page more 
scannable, structural cues are visual cues for processing the page. For 
example, in this page:

http://drupal.org/node/33958

The wrong markup is being used because embedded headings have been 
forbidden. If this page were encoded and then "structured" correctly 
according to the current standards, it would affect readability because 
each of these paragraphs would be their own page. The reader would no 
longer be able to scan the headings and skim the paragraphs, but rather 
would have to click through each as a separate page. Nor can the reader 
skip around and return back as easily without having to revisit pages 
(sometimes we skim forward, then come back to what we judge the most 
important)

As a consequence, the handbook is currently difficult to read because 
many pages which might be better presented as one page have been broken 
up into multiple pages. It is click heavy. At times when drupal.org, 
reading speed is further reduced unnecessarily because of a policy.

A separate issue, has to do with the rhetorical effectiveness of pages. 
Presenting readers with hyperlinks provides them with choices where they 
have to decide to view another page or not to and which page to view. 
For example, when the reader gets to the end of the paragraph of this page:

http://drupal.org/node/10250

they are presented with visual cues which say "Stop. Decide whether to 
read forward. Decide which link to follow." If those subpages were 
included in this page with headings, that "Stop" sign becomes less 
emphatic and the headings become structural cues which let the reader 
know that the topic is changing, but they are not pushed to make a 
choice. They are encouraged to read on. However, instead of the text 
being structured based upon which is the best strategy of these two for 
presententing information, we have chosen to limit ourselves to always 
putting that stop sign up even when it may not be the most effective 
rhetorical strategy.