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

[Charlie Lowe]

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.

Prior to last spring, many of the handbook pages were overly long and 
needed to be broken up into multiple pages. At the same time, there was 
the idea that the handbook would eventually be exportable and maybe even 
turned into a printed edition. Thus, not using embedded headings worked 
better with Drupal's limitations for exporting the book in XML.

For a while, there was an export to DocBook XML feature included with 
the handbook. However, that has been removed from core. Nor has there 
been much work on creating a printed edition (I'm not convinced this is 
going to happen in the near future).

So I, personally, would not mind seeing this changed for the reasons you 
present here. Sometimes, breaking a text up by headings is not the best 
way to present a text. Also, because of the lack of headings, people are 
merely using <strong> tags instead for different sections in a given 
page, moving us away from semantically rich markup.

To get this changed, you should raise it as a separate topic/thread on 
the documentation list. If there is a consensus that prudent use of 
embedded headings in pages is the way to, we can modify that policy.

Charlie Lowe