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

[Robert Castelo]

For me the two highest priorities for the handbook are:

1) being able to find the right page
  - increasingly difficult now that we have so much documentation

Breaking a page up into small sub-pages makes it more difficult to find 
the right page through a search engine, which rates the relevance of a 
page by keywords appearing in headings and sub-headings and also how 
often the keyword appears throughout the page - I think this also 
applies to Drupal's built in search engine.


2) readability of the page
  - how much effort is required to read everything on that page

Obviously scrolling down one page is a lot less work than locating and 
clicking through x number of links, this becomes specially important 
for users with degraded motor skills and the visually impaired.

If there's a problem exporting markup with sub-headings, could we not 
deal with that at the code level, parse the output and break it up into 
sub-pages on export?




Best regards,

Robert