|
Dana et al.,
I would fully support deprecating nested topics. I believe
they cause more problems than they provide advantages. They were apparently
included originally to accommodate legacy documentation. However, I continue to
advise people to use maps and nesting in maps to accomplish the same thing--to
show some hierarchical relationship between topics if that is needed for
readers.
When Ginny Redish and I helped Hewlett-Packard develop
their worldwide Editoral Design System in 1991, we recommended a flat structure
for user documents. Usability studies told us that elaborate hierarchies of
topics are essentially lost on users of technical documents. Most readers do not
distinguish more than three levels of heading at all.
People do not use technical documentation in a way implied
by hierarchical nesting. They look for the topic they need know and do not
consider the arrangement.
Elaborate nesting is a leftover from military manuals and
legal documents that use numbered sections ad infinitum. Even in this context,
it's not clear what the hierarchies accomplish except to confuse
readers.
Let's define topics as standalone as we have and consisting
of a minimum content with title and at least one paragraph of text -- that
should be sufficient. I wonder what others consider a precise definition.
JoAnn
JoAnn T. Hackos, PhD
President
Comtech Services,
Inc.
710 Kipling
Street, Suite 400
Denver CO 80215
303-232-7586
joann.hackos@comtech-serv.com
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
|