RE: [dita] Nested Sections

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

Good points. I think you are right that
there is a continuum between headings that are more section-like and those
that are more topic-like, and so for example you might have a generically
titled heading that looks like a section but has its own prolog needs and
related links, and so ends up being most usefully modeled as a topic.

I tend more towards topics than sections
as a solution for most cases, simply because a false positive is better
than a false negative. IE, if something is misidentified as a topic when
it's really a section, the worst we've done is make something easily reusable
that nobody cares about. But if something is misidentified as a section
but needs to be reused or referenced like a topic, then it will need to
be rewritten by the original author.

In other words, if we err on the side
of topics, then control of reuse is in the hands of the reuser; if we err
on the side of sections, then reuse is bottlenecked by the ability of the
original author to migrate over time into a more topic-oriented model.

In the case of online indexing or navigation,
you have a point that sections are typically not candidates for inclusion;
but I don't think we can safely assume from this that anything not included
in the navigation must therefore be a section. For example, API documentation
typically surfaces in the TOC by class name, even if each method/attribute
is modeled as a child topic; and tutorials or other more complex documents
also typically have one entry in the TOC, even when composed of multiple
topics. In other words, the issue of which topics to include in navigation
is with us regardless of the section/topic distinction; it's one of the
reasons the map includes the toc attribute.

Michael Priestley
IBM DITA Architect
SWG Classification Schema PDT Lead
mpriestl@ca.ibm.com

"Esrig, Bruce (Bruce)" <esrig@lucent.com>

11/03/2005 11:37 AM

To	"'Don Day'" <dond@us.ibm.com>, Deborah Aleyne Lapeyre <dalapeyre@mulberrytech.com>
cc	dita@lists.oasis-open.org
Subject	RE: [dita] Nested Sections

One place where the sides differ on this is in the
criterion "a topic should be able to stand alone". To clarify
what is meant by "stand alone", it's important to also specify
the context in which a topic is expected to stand alone.

By topic, do we mean something that is responsible for its own links to
other topics that it depends on? Or can a topic be something very primitive
and section-like that is highly dependent upon the environment in which
it is presented in order to define its context?

We have found cases (in on-line training) where a section-like chunk needs
to stand alone and rely on the presentation environment for its context.
If sections can't nest, then a way to map these into DITA would be to use
the topic structure for these and simply not use the extra features of
topic. But what we do now is mark them with a section-like element and
then extract them for training.

Some of our section-like chunks do have nested titled chunks within them.
That by itself doesn't make them into topics in the strongest "stand
alone" sense. Forcing authors to use stand-alone topics to encode
these chunks would increase the number of chunks that qualify cosmetically
as topics, and leave us with a further issue of identifying which ones
are truly intended to stand alone in less navigation-rich environments.

To avoid mentioning books, let me ask instead about an online support environment
in which certain titles are worthy of being in the catalog (whether the
catalog is literal or simply a designation of which titles are worthy results
of a search). If we (in specifying the DITA language) inflate our population
of topics by not supporting nesting, we (in using the DITA language) will
want to distinguish cataloguable topics from the rest.

Best wishes,

Bruce

-----Original Message-----
From: Don Day [mailto:dond@us.ibm.com]
Sent: Thursday, November 03, 2005 11:16 AM
To: Deborah Aleyne Lapeyre
Cc: dita@lists.oasis-open.org
Subject: Re: [dita] Nested Sections


Debbie, could you give any scenarios based on experience that you've had
with customer data?  It might be interesting to evaluate those cases.

And given that DITA is implicitly a topic-oriented architecture, what
exactly does "non-topic level" mean?  Perhaps the issue
is more about how
to migrate non-topic content into DITA?  I could see this for incoming
Word
or Framemaker content, for example.

Regards,
--
Don Day
Chair, OASIS DITA Technical Committee
IBM Lead DITA Architect
Email: dond@us.ibm.com
11501 Burnet Rd. MS9033E015, Austin TX 78758
Phone: +1 512-838-8550
T/L: 678-8550

"Where is the wisdom we have lost in knowledge?
 Where is the knowledge we have lost in information?"
   --T.S. Eliot


                    
                     
                     
          
             Deborah Aleyne    
                     
                     
             Lapeyre      
                     
                     
    
             <dalapeyre@mulber  
                     
                 To 
             rytech.com>    
          <dita@lists.oasis-open.org>  
      
                    
                     
                     
       cc 
             11/03/2005 08:40    
                     
                   
             AM        
                     
                     Subject
                    
                  Re: [dita]
Nested Sections          
                    
                     
                     
          
                    
                     
                     
          
                    
                     
                     
          
                    
                     
                     
          
                    
                     
                     
          
                    
                     
                     
          




Sections should nest.

It may be rare, but it will happen, at the non-topic level.

--dal
--
======================================================================
Deborah Aleyne Lapeyre              
mailto:dalapeyre@mulberrytech.com
Mulberry Technologies, Inc.              
 http://www.mulberrytech.com
17 West Jefferson Street              
     Direct Phone: 301/315-9633
Suite 207                  
                     
 Phone: 301/315-9631
Rockville, MD  20850              
                  Fax: 301/315-8285
----------------------------------------------------------------------
  Mulberry Technologies: A Consultancy Specializing in XML, XSL, &
SGML
======================================================================