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

[puregin]

On 12-Jan-2006, at 6:17 AM, Charlie Lowe wrote:
>
>
> 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
>

     Charlie, I'm sure we both agree about the usefulness
to the reader of headings.

      My point is this.  Look at the printer friendly
version of any handbook section.

      Can you tell whether a given heading comes
from a node title or an embedded heading?  No.

     Hence whether a heading on a page/screen
comes from an  embedded heading, or is a
structural title,  is of  interest only to authors/editors.

     If given content is not *presented* in a
way that is useful to the reader, that is another
matter, but again, it does not have to do with
how headings and structure are represented.


> 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)

     I'd argue that the wrong markup is being used because the
interface for browsing books is not well designed.

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

      We both agree that the present documentation is difficult to read.

      I think the fix is twofold

          1)  improve the *structure* and presentation of the  
documentation
          2)  improve the book browsing interface.

     Using embedded headings is a dirty hack that makes
it difficult to edit and maintain the documentation,
which actually goes against 1),  in the process of
trying to avoid the pain of 2)