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] What Is A Topic


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

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