[drupal-docs] Transitioning to header-free book pages (was Re: Styleguide)

[puregin]

Hi Bryan/Doc people -

     I've tried to tackle the section you suggested to illustrate a 
proposed process
for transitioning documentation from 'embedded header' format to
a header-less format.

     I've posted the results on my site:

        http://www.puregin.org/node/127

(I apologize for my somewhat broken attempt to 'improve'
the themeing of book module.  Sigh.  Also, Konqueror seems
broken on my CSS, and I've not dared try IE.  Sigh again)

     There's three subsections, one for each of

          - the current structure
          - the transitional structure (embedded sections extracted as 
children)
          - a conformant structure (no embedded html header elements)

     My take on current structure:
          - section titles don't appear in navigation context - it hard 
to find context
             without reading a fairly long page, with potentially quite 
diverse content
          - there's too many headers, and levels of headers, which 
breaks up the
            text, without clarifying structure.   For example, a section 
titled "What are
            blocks" isn't really necessary as the first subsection of a 
sections "Blocks".

      The transitional structure reveals structural problems with the 
original:
          - there are some sections now which have no content, only 
children.
            This begs for content to be 'pulled up'.
          - The hierarchy of sections is too deep
          - Structure is manifest (all headers are revealed in the 
navigation block)
             but somewhat redundant.

      My attempted 'conformant' rewrite attempts to remedy the issues 
above.
          - Structure is still manifest
          - By pulling content up and removing redundant structure, the 
structure
            supports the content
          - The hierarchy has been collapsed to three levels within 
'chapters'
          - Each node is shorter, and more focussed.  There's nothing 
'below
            the fold' except in the examples subsections.
          - There's still lots of room for improvement :)

      Some notes I made the in the course of this:

           - it would be nice to have a 'make a copy of this book page'
             function which would make a copy as a sibling of the
             page being viewed.

           - I'm thinking that the user interface for viewing a book 
should
             present quite a different view than the editing view.
             I'm thinking something along the lines of a paged
             HTML view of the 'Printer friendly' output of the entire
             subtree being edited.  If the navigation block could
             track the position within the book as one paged
             through the text, that would be very useful.  (I'm
             thinking of something much like most PDF viewers)
                     There's (at least) two simultaneous and valid
             models of what a book is - a writer/editor often
             thinks of the local hierarchical structure; while a
             reader probably more often sees the local
             linear structure.

     I'm looking forward to your feedback.

     Djun


On 26 Apr 2005, at 6:38 AM, bryan kennedy wrote:

> On Apr 26, 2005, at 7:35 AM, Dries Buytaert wrote:
>
>> I think I'm convinced ... maybe we should try not to use headers in 
>> book pages.  As long the book's depth stays within the agreed range, 
>> I'm OK with the proposed work.
>
> Okay I am still way confused about how this would work.  I mean I 
> don't get how we will decrease the navigation depth with out making in 
> each subsection super "wide" while eliminating headers in the content 
> of the book pages.
>
> But I am totally willing to be convinced.  Could someone take a stab 
> at describing how they would restructure this content (broken up into 
> two main header sections, five sub header sections) within the other 
> 18 items below it.  Please emphasize why this would be beneficial to 
> the user experience:
> Blocks
> http://drupal.org/node/17170
> I am not trying to be obstinate I guess I just haven't seen any 
> examples of how this would work.
>
> I would also like to re-iterate my belief that we are building a 
> website, not a book.  Yes, it would be awesome if we could take the 
> content from our website and do a book friendly output, but IMO the 
> people who want this are a minority audience (even if a majority of 
> devel on this list want it).
>
> bryan