OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: RE: [dita] Nested Sections

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

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

11/03/2005 11:37 AM

"'Don Day'" <dond@us.ibm.com>, Deborah Aleyne Lapeyre <dalapeyre@mulberrytech.com>
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,


-----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.

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                                                
            <dalapeyre@mulber                                          To
            rytech.com>               <dita@lists.oasis-open.org>        
            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.

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

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]