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

[Charlie Lowe]

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

I do understand what you are saying, and have understood this. The main 
issue that needs to be addressed is how to represent the visual headings 
within a handbook page. This is the point where the conversation always 
stops. You are concerned about the structure of the book. That's fine. 
But I am equally if not more concerned about the structure of individual 
pages--how visual headings can be used within a page. Here's an example:

http://cyberdash.com/files/misc/heading-example.png

In this page, I do not want to break this into multiple pages (for the 
reasons mentioned about hyperlinks and wanting the reader to be able to 
scan the text). The structure of the book is already defined for this 
text. Headings here are used being used within an individual page for 
structuring as visual cues that would not be better served breaking it 
up into multiple pages.

Nor should we deny documentation writers from using headings (visual 
headings, not embedded HTML headings) within a page because we are 
afraid the pages might end up be being too long. If this happens, 
documentation moderators can always break the page up. But neither do we 
want to break up every page based upon the use of headings as we are 
currently doing. There are some pages and subpages on drupal.org where 
this is the less effective way of presenting the documentation to the 
reader. The most usable solution for users of the handbook on drupal.org 
is a balanced approach that takes into consideration strucuture of pages 
within the book and structure within individual pages.

So, if embedded headings are used exclusively for defining the structure 
of the book pages, and, as you say, to the reader it makes no difference 
how it is coded to them, how would you code the visual headings which 
appear within a handbook page? Would you advocate that we use 
<p><strong> tags for headings within a documentation page? This needs to 
be explained in the documentation which says not to use embedded 
headings so that people know what to do.