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

[puregin]

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