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

[nathandigriz]

puregin wrote:

>
> On 11-Jan-2006, at 6:44 PM, Charlie Lowe wrote:
>
>>
>>
>> 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.
>>
>
>     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.
>
>    Nathan may rightly complain of the way in
> which the handbooks are presented,
> and the way navigation works;  that is
> a separate issue.
>
>    The same observation applies to
> the argument about motion impaired
> readers, however small a fraction of
> our readership that may be.
>
>     In the end, it is the TEXT and the
> INTERFACE that matters, not the
> underlying REPRESENTATION, which
> the reader never sees.
>
>>
>> Prior to last spring, many of the handbook pages were overly long  
>> and needed to be broken up into multiple pages.
>
>
>     The reasons for avoiding embedded headings
> still hold:  http://drupal.org/node/24221
>
>
>> 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.
>
>
>     Exporting as XML has nothing in particular to do with this.
>
>     The issue is that structure is provided by the book
> hierarchy, and authors should use structural means to
> imply structure.
>
>      A deeper issue, I feel, is that there is a LACK OF
> STRONG CONTENT OUTLINE for the handbooks.
> Thus, the books are muddled in places.
>
>>
>> For a while, there was an export to DocBook XML feature included  
>> with the handbook. However, that has been removed from core.
>
>
>    The various export options are alive and well.
> I expect that they will be available on Drupal.org
> (to those with appropriate permissions) when
> Drupal.org moves to 4.7.
>
>
>> Nor has there been much work on creating a printed edition
>> (I'm not convinced this is going to happen in the near future).
>
>
> Everything required to produce print
> output  from the Drupal handbooks via DocBook XML
> is in place, waiting for Drupal.org to move to
> 4.7. This has been the case since August.
>
>     The main thing obstacle at the moment
> to making to a print edition, in my opinion,
> is the lack of organization of the content.
>
>     Fortunately Steven Peck, among others,
> seems to be making some progress here.
>
>     The issue is not technology.
>
>     The issue is that its bloody hard to
> organize and write a tech book, especially
> if it has many audiences, and many
> authors.   Encouraging  embedded
> headings will make editing and
> structuring MUCH more difficult.
>
>> 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.
>
>
>     HTML is NOT semantially rich markup.
> Headings may suggest structure, nodes in
> hierarchy ARE structure.
>
>> 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.
>
>
>      But let's not, because we've been through
> that.
>
>
>     Djun
> -- 
> Pending work: http://drupal.org/project/issues/documentation/
> List archives: http://lists.drupal.org/pipermail/documentation/
>
How would header  be set as a standard without using HTML's built in 
structure. <p><strong> ,<p><u>,<p><em> does not work very well with 
thousands of pages and also make the creation of  XML and PDF more 
complicated and make xhtml compliace a nightmare . It also  does not 
allow for  global  formating with CSS.  It  may force someone to use a 
span tag or worse a font tag to size text, I am sure no one wants to see 
this happen.  And again it is not BOB safe. How do you get around the 
problems associated with HTML without using it as per W3C guidelines?