I agree with Paul generally, although
I also think that legacy docs can be migrated into DITA using nested topics,
although at the cost of best practices. IE, you can't make legacy docs
topic-oriented automatically, but you can typically fit them into a topic-oriented
doctype if you want to migrate first and rewrite later.
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.
- 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 is the point at which "makes
sense on its own" becomes clearly exposed as more of a guideline than
an absolute requirement. Just as you might want to bend that rule to fit
legacy docs, you might also want to bend it for container topics (sometimes
they have enough content to stand on their own, sometimes they're the container
for generated summaries of other content, sometimes they're just a navigation
hub to other resources). The important thing is that the topic title is
still an accurate reflection of the destination.
I'd support adding some softening words
to the topic-oriented section if that would resolve the current conflict.
Current wording:
>>>
A topic is a unit of information with
a title and content, short enough to be specific to a single subject or
answer a single question, but long enough to make sense on its own and
be authored as a unit.
>>>
Proposed softening:
>>>
A topic is a unit of information typically
consisting of a title and content, short enough to be specific to a single
subject or answer a single question, but long enough to make sense and
be authored as a unit, often on its own.
>>>
We might also consider adding a specific
section on container topics and small topics - we could call it "limits
of topic orientation", equivalent to the "limits of specialization"
topic later in the spec. That would give us a place to talk about some
of the edge cases in detail without overly weakening the main points of
the section on topic orientation.
Michael Priestley
IBM DITA Architect and Classification Schema PDT Lead
mpriestl@ca.ibm.com
http://dita.xml.org/blog/25
"Grosso, Paul" <pgrosso@ptc.com> wrote
on 12/21/2006 10:42:00 AM:
> I don't disagree with Eliot and Scott that the wording about
> topics could perhaps be clarified a bit, though I consider
> that mostly editorial and not a substantive issue in the spec.
>
> I don't have much of an opinion about title-only topics or such.
> It's difficult for the DTD to enforce good practice anyway, and
> no matter how hard you try, a determined user will figure out
> how to do something they probably shouldn't do. (Your bullet,
> your gun, your foot.)
>
> I will say, though, that I have less sympathy with the legacy
> conversion issue. DTDs in general--and whole technologies like
> DITA in particular--are designed to be optimized for a specific
> set of requirements and expectations. If a square peg doesn't
> fit into a round hole, you don't mess up the hole, you do something
> about your peg or you look for something with square holes.
>
> I don't know if DITA sections should be nestable (some in-house
> Arbortext users did ask for this too, but again, I think they
> were trying to figure out how to map DocBook into DITA), but I'm
> pretty sure I don't want to be driving DITA design by considerations
> of legacy conversion.
>
> If you've got stuff tagged using another tag set/DTD, my first
> question is why retag it? What's wrong with the way it is now?
>
> If there are really good reasons why it is actually worth the
> effort to retag it using DITA, then by definition, there should
> be good reasons to *rewrite* it in a topic oriented fashion rather
> than trying to cram non-DITA-isms into the DITA mold.
>
> Perhaps I'm over-reacting to the word "legacy", but I think
we
> need to consider extensions to DITA in light of actual topic
> oriented related requirements rather than conversion issues.
>
> paul
>
> >
Original Message-----
> > From: Scott Hudson [mailto:scott.hudson@flatironssolutions.com]
> > Sent: Wednesday, 2006 December 20 18:03
> > To: W. Eliot Kimber
> > Cc: dita@lists.oasis-open.org
> > Subject: Re: [dita] What Is A Topic
> >
> > I very much agree with Eliot, and have run into similar legacy
> > conversion issues.
> >
> > I do think we need to disallow title-only topics, but I think
we may
> > need some other components that are smaller than topics. These
> > components could be used to better model "transitional text",
> > too. The
> > current hack to create transitional "topics" seems
to defeat the
> > definition of the ability for topics to stand alone.
> >
> > Best regards,
> >
> > --Scott
> >
> >
> > >
> > > At a minimum, I think the specification needs to be internally
> > > consistent on what the explicit and implied rules for
> > topics are. At the
> > > moment, the specifications and statements such as the
> > second one are
> > > inconsistent with the initial (and primary) definition of
"topic".
> > >
> > > Either we have to disallow title-only topics (which I don't
> > think we can
> > > do at this point since we have to be backward compatible
> > with 1.0) or we
> > > have to relax the initial definition to make it clear that
> > topics are
> > > not required to have bodies nor are they required to make
> > sense on their
> > > own, but can in fact be just titles.
> > >
> > > Cheers,
> > >
> > > Eliot
> > >
> >
> >