[drupal-docs] Styleguide

[puregin]

On 25 Apr 2005, at 4:16 AM, Moshe Weitzman wrote:

>>
>> There are two (related) problems: violation of encapsulation, and 
>> violation of separation of presentation and content. I'll expand:
>>
>> Headers suggest a hierarchical structure, and so does the book 
>> module's hierarchy.   These two schemes for structure can quite 
>> easily be in conflict.   At the same time, HTML's definition does not 
>> give control over ordering of h1, h2, etc. elements.   So it's 
>> possible to write valid HTML with an H1 section 'inside' an H2 
>> section, for example.   This is syntactically valid but logically 
>> silly.  Book module at least enforces its hierarchy.
>>
>> If you're putting H1, H2, ... elements inside of a book page for a 
>> reason other than sectioning, you're violating the 'intent' of these 
>> elements, i.e., using the header elements as presentational markup.   
>> This is asking for trouble, for reasons which I hope are well 
>> understood.  If you are trying to indicate structure, why not let 
>> book module handle it?  Isn't that its main purpose in life?
>>
>> In addition, preventing 'internal sectioning' would lead to smaller, 
>> flatter nodes, which should be easier to read, to edit, and to 
>> navigate.
>
> i wonder if someone would make these statements after writing a bunch 
> of book pages. The statements sounds nice, but are impractical. We 
> *should* to provide some approved way for authors to add structure 
> within a single page. And a list does not always satisfy this need. To 
> describe all but the most simple concepts, you want structure.

Moshe,

If you are asking about the base of experience from
which I'm basing my views, I'll give you a little background.

I've written published one book, and am currently about 65%
finished a second, both in the field of Geometric Topology.

I've served as chief technical editor and production manager
for three years on a project in which a team of about 25 part-time
contributors produced 600 pages of mathematical manuscript per year.

I was principal architect and developer on a project which
converted over 10,000 pages of automotive service manuals
into an XML database, based on a customized version of
DocBook, for republication in a variety of formats including
print and HTML.

I'm very interested in practicality.   But my view of this
is based on the 'project scale', not merely at the
level of convenience for individual authors, though
of course this is a very important consideration.

There's usually a tradeoff between letting an author
do whatever she is most comfortable or familiar with,
and dealing with issues  of scale when one goes from
a single author and a single  "article/node/page/chapter",
to the level of editing an entire  book or series.

I suspect that quite a few of the existing
handbook nodes were written offline and pasted into  a
single page because it was convenient.  That might save
the author a few minutes at the time, but it makes for a
document with ambiguous structure, as I've pointed out.
It also creates real maintainability issues.

I agree absolutely that we want structure.
But let's have real structure, and not merely
the appearance of structure.

>
> If we force authors to create subpages every time they want structure 
> we will not end of with "smaller, flatter nodes which are easier to 
> read and navigate". We will end up with deep, annoying hierarchies 
> where it takes 7 clicks to get to the damn URL for the Contrib 
> repository (e.g Handbook => Contributors Guide =>  Development => CVS 
> => Repositories => Contributions => Configuration). Another example 
> might be a page like http://drupal.org/node/12352. We should not 
> recommend that authors break up such a page into many subpages, IMO
>

Let's be concrete.  In the handbook as
at April 21, 2005, there are 414 instances of header
elements in book pages.  All but one or two are
manifestly "structural headers";  making the associated
text child would give the same presentation and give
genuine structure.

These are contained as follows:

container:                          count:
----------------------------------------------------
    book-h2 (chapter)        107
    book-h3 (section)         227
    book-h4 (subsection)    75
    book-h5 (sub-sub)           3

About eighty-five nodes would need to be split.

The top ten of these account for approx. 150 of the cases.

The maximum internal hierarchy depth is three.

In no case would the resulting true hierarchy be
deeper than 6 when we split.  *Thus the fears of
excessive nesting are unfounded.*

The existing handbook hierarchy has depth 6
(sub-sub-sub section of part-chapter-section)

I agree with Dries that the handbook hierarchy should
be no deeper than sub-sub-sections
(e.g. Section 1.2.3 is OK, but 1.2.3.4 is pushing it.)

If we are to edit to achieve this, we surely must do so
by editing book structure, rather than by cutting and
pasting within and between nodes.  The only way this
would be possible is to have true structure, that is,
no header elements inside pages.

Rather than making navigation more burdensome,
as you suggest, splitting nodes will improve matters
by making the 'false headers' into true sectionals,
which will appear in the navigation hierarchy and allow
users to find them by clicking on them.

*At present, users have no way of discovering that an
embedded section exists except by scrolling
down possibly very long pages.*

Adding a child page is so much easier now that
the 'add child page' feature has been implemented,
so I don't believe that this will be too much of a burden
on authors.

Finally, if this proposed style guideline is accepted,
I commit to editing the existing handbook to bring it
into line with the proposed change,  and to helping
to improve book module to make the editing and
reading experience even easier and richer for users.

>
--
Djun M. Kim, Director                           
djun.kim at cielosystems.com
Cielo Systems Inc.                              
http://www.cielosystems.com
Strategic Software Research                     Tel:   (604) 739-3941
302 - 1298 10th Avenue West                     FAX:   (604) 739-3943
Vancouver, BC, V6H 1J4                          Mobile:(778) 895-1379