MHonArc v2.5.0b2 -->
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
mpriestl@ca.ibm.com
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