Re: Fw: WG: [dita] Status of Nested Sections Issue

[Michael Priestley <mpriestl@ca.ibm.com>]

Chris, can you clarify why nesting topics
wouldn't do the trick? It's not clear to me why nesting topics would be
substantially different from nesting sections, except that nesting topics
preserves the definition of modular content for DITA, whereas nesting sections
allows topics the size and complexity of entire books, which would mean
that being in DITA has nothing to do with being modular.

In other words, right now a lot of DITA's
messaging is about content modularity and topic orientation. All of that
messaging is based on topics having some kind of common size or complexity.
The only limit we have on a topic's size or complexity is the enforcement
on non-nesting of sections (effectively, if you have more than one level
of section, then experience tells us you have more than one topic).

So if we allow sections to nest, we
are undermining one of our core DITA messages, and one of our main differentiators
from other standards. On the plus side, we would be able to say that we
can now handle any content, regardless of topic orientation; on the minus
side, we would not be able to say that DITA is a modular content architecture
with any special claim to enabling reuse.

That said, it also makes sense that
content goes through stages, and whether it's new content being jammed
into a big readme or migration of existing content that hasn't been chunked
yet, there's always cases where you need a single document with multiple
levels of heading, which you intend later to break apart for more effective
reuse etc. 

But my understanding was that we allowed
complex documents (eg through the ditabase doctype) to support this continuum
- you can create a big complex nested document using ditabase, then rechunk
it later into smaller documents with an accompanying map. That's all do-able
today, and has the virtue of protecting the identity and integrity of individual
topics through the content lifecycle. 

What is it about this use case that
makes nesting topics inappropriate? To me, it looks like exactly the use
case that drove us to allow nesting topics to begin with, and I don't understand
why we need to nest sections as well, at such a high cost to DITA's core
focus.

From our charter:

>The work of this TC will differ
from similar efforts such as DocBook because of
> - broader scope, inasmuch as DITA
applies to more areas than just technical manuals 
> - more specific scope, inasmuch
as DITA applies to topic-oriented information rather than all technical
manuals 
...
>DITA topics
> - can be assembled in different
combinations for many deliverables or output formats 
> - are optimized for navigation
and search 
> - are well suited for concurrent
authoring and content management 
> Through use of a common specification,
DITA content owners can benefit from industry support, interoperability,
and reuse of community contributions.

Michael Priestley
IBM DITA Architect and Classification Schema PDT Lead
mpriestl@ca.ibm.com
http://dita.xml.org/blog/25

"W. Eliot Kimber" <ekimber@innodata-isogen.com>

10/17/2006 10:50 AM

To	dita@lists.oasis-open.org
cc
Subject	Re: Fw: WG: [dita] Status of Nested Sections Issue

Don Day wrote:
> -----Ursprüngliche Nachricht-----
> Von: Christian Kravogel [mailto:christian.kravogel@seicodyne.ch]
> Gesendet: Dienstag, 10. Oktober 2006 17:03
> An: 'dita@lists.oasis-open.org'
> Betreff: RE: [dita] Status of Nested Sections Issue
> 
> Eliot
> 
> The issue of nested sections looks to me of something of high importance
> and
> the source for controversial discussions. I am working in technical
> authoring since 12 years, most time in the machine industry (elevators,
> escalators, etc.) and I noticed that if you give an author the ability
to
> nest topics and to nest sections it will become a mess indeed and
some will
> screw-up most structured content.
> 
> On the other hand, there are companies with special requirements and
they
> absolutely need the ability to nest sections. The example of implementing
> legacy data is a very good approach. Different industries and different
> departments have different requirements. And when we think of DITA
users,
> we
> should not limit that to the view of a technical author writing an
> installation instruction of a mechanical device or writing an API
user
> manual.
> 
> Maybe we should not able section to nest, but we may add a separate
block
> element that can be used for specializations to enable block nesting.
E.g.
> the <div> element known from HTML (like you already mentioned).

I don't see that it makes that much difference whether you allow section
to nest or add a new element type that is equivalent to section but that
can nest.

In either case specializers can impose whatever local constraints they
want, either disallowing nesting or creating a limited nesting level (by
having unique specializations at each level) or by defining more 
semantic section types.

The question of what authors will do with the ability to nest and having
two different ways to do things has always been a problem and will 
always be a problem. That's because it's an *editorial* problem, not a
technology problem. Even if you disallow it (as the current DITA 
specification does) authors will just do something different if they 
have to.

That is, there is and can be no substitute for well-trained writers, 
appropriate editorial oversight, and clearly-defined editorial policies.

In addition, no matter what the DITA schemas say (or what any other 
schema designed for document authoring says), you *ALWAYS* need some 
sort of "validation application" that validates rules that cannot
be 
expressed in a DTD or schema. This is either a separate application or
a 
side effect of the error checking or failure behavior your processors 
provide. In either case, since you have to do this checking you can 
always add checks for editorial rules for things like section nesting,
a 
requirement that there be at least two subsections under a section, that
sort of thing.

In 1.1 I think that simply allowing section elements to nest is the 
simplest solution that meets the requirement, requiring no additional 
design, no additional element types, or anything.

Adding a new element type would involve more changes to the 
specification and open up more debate about exactly what the rules for
that new elemen type should be. That level of design does need to be 
pushed off to a later version.

Cheers,

Eliot

-- 
W. Eliot Kimber
Professional Services
Innodata Isogen
9390 Research Blvd, #410
Austin, TX 78759
(214) 954-5198

ekimber@innodata-isogen.com
www.innodata-isogen.com