Personally, I'd like to see the definition of topic
beefed up and kept in the standard, rather than watered down and
demoted to a best practice merely.
One of DITA's prime distinctions is being a topic-oriented DTD, as
opposed to, say, DocBook. Remove that, and you muddy its
distinctiveness.
On the other hand, I agree with Eliot that inconsistencies have
developed between nested topics and maps.
Perhaps nested topics should be deprecated, and maps promoted as the
preferred means to collect hierarchies of topics.
If particular organizations still want to use DITA against the grain -
well, there are always ways to accomplish that.
Happy New Year!
--Dana
W. Eliot Kimber wrote:
Michael
Priestley wrote:
On the issue of title-only topics in
particular I wanted to add a few things:
- a small topic may legitimately need only a title and short
description - our own glossentry specialization comes to mind. Some
forms of context-sensitive help are also likely to be very short, and
with the addition of abstract, easily accomodated without the
<body> element.
Hmmm--I'll have to think about this more.
- a topic may start small and grow over time
into a whole branch of topics. The container topic may be no more than
a title and child links (or just a title, with child links managed via
a map). But the container topic is still important as a link
destination, because it still answers the question it originally
answered when it was just a leaf-node topic. People who link to the
topic shouldn't be forced to recode or break their links just because
the topic has changed from leaf node to container node. In terms of its
subject, it's still the same topic.
This suggests to me that a different structure is needed rather than
trying to have topic do double duty as both a coherent direct container
of content and as simply a titled container.
For example, I'm starting to think that it would make sense to allow
topichead wherever topic is currently allowed (possibly with a bit of
augmentation). This works well in maps so why not allow it in topics as
well? [But then would what it mean to have a document whose root
element is topichead--not sure and I can imagine that Michael would
immediately object to the possibility, which probably he should.]
On the other hand, I could easily accept Michael's more flexible
concept of topic if we, as he suggests, add some discussion of how
these two different uses of topic are intended to be used and what
would likely constitute abuse of them.
Clarifying question: When you say:
"The container topic may be no more than a title and child links"
Do you mean using links from the related-links section with a semantic
of "child"?
I ask because topic does not allow topicref where it allows nested
topics (I originally expected them to be allowed) so I'm assuming that
related links is the intended way to create explicit hierarchical
relationships from within a topic to other topics. But then that raises
the issue of there being three distinct ways to do it (with a map using
topicrefs, with links, and with nested topics)--which approach do you
choose when?
This question is somewhat driven by a question related to "what is a
topic" which is "when do I use a map to express a unit of re-use
(composed of a set of topics that don't have any real individual
meaning) and when do I use a topic with nested topics?"
That is, the implication of Michael's reasoning for having title-only
topics that then just point to other topics is that they serve as a
consistently-available link target, which is definitely good. But given
that I could do the same thing with a map and topichead, which *should*
I do?
If I say "use maps for all collecting of topics" then it leads to the
conclusion that there is a very real sense in which the map and the
equivalent title-only topic are serving exactly the same rhetorical and
practical purpose, which then suggests that either there's a need for a
different kind of map that is really a specialization of topic or
something.
But I do keep coming back to the possibility that the distinction
between maps and bodyless topics is very slight and that perhaps it
would make sense to unify them by allowing topic to allow topichead and
topicref where it currently allows nested topics.
I also think that Michael's use case of a topic evolving from being a
singular chunk of information to the root of a tree of related topics
is a compelling one--it seems not only likely but inevitable.
However, I'm not convinced that the right solution is simply keeping
the original topic around as a navigation target--given an appropriate
indirection mechanism (and corrected addressing scheme) you could just
as easily replace the original topic with a map (I can't do that today
because the *syntax and semantics* for addressing maps and topics is
different even though they probably shouldn't be).
That is, maybe there are really two distinct types of maps: maps that
define entire units of delivery and maps that define units of re-use
that are functionally equivalent to topics with tested topics and/or
topics with child links to other topics.
To my mind, it certainly seems intuitive to use maps for all organizing
of topics and it makes sense from a consistency of tools and work
practice, but it doesn't, at the moment, seem to fit as well as it
could or should with the current markup design. Thus my quandary.
So I think there's definitely room for refinement in our collective
understanding in how to best address these issues of representation of
collections of topics that form coherent (and necessary) hierarchies in
order to convey a single "true" topic.
Cheers,
Eliot