Grosso, Paul wrote:
> 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.
That may be the intent but the fact is that it's in a normative section
of the specification and, given that there is no other formal definition
of "topic", it must be taken as the normative definition of what a topic
is. One solution would be to rewrite the sentence to make it less
definitive, i.e.,
"A topic is usually taken to be 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."
But I think the fact that Paul and I could even have this difference of
interpretation points to a problem with the specification as written, in
that it is not nearly as formal as many of us have come to expect
standards to be (especially those of us raised in the Charles Goldfarb
school of Standards Written By Paranoid Harvard-Trained Attorneys).
DITA, by it's nature as a generic, enabling, application standard is
inherently fuzzy but that shouldn't give us license to leave unclear key
distinctions and definitions.
For example, it's clear that both Michael and Don D. have clear, and I
think, consistent ideas of what is and is not a topic, but it's not
clear to me that those ideas are either definitive (that is, do they
match the *community's* idea of what is and is not a topic) or crisply
conveyed in the specification. But the issue of what is an is not a
topic is clearly of central importance to DITA, both as it's used within
IBM and as its understood by (or imposed on) the larger DITA user
community.
> 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.
I generally agree with Paul, except...
In my case, the legacy is unstructured documents that reflect a
long-established practice within an industry. So while everyone involved
agrees that the writing approach may not be optimal, it's also not
necessarily possible or practical to completely change the structure and
approach of the documentation as cost of entry to the use of DITA (which
is otherwise clearly indicated in this case).
So that leaves the problem of how to do an *initial* mapping of the
legacy to DITA structures with the minimum amount of disruption to the
existing structures while being as true as possible to both the intent
of DITA and the letter of the specification as well as to established
practice (to the degree that there is any for DITA).
That is, while I agree that ideally all uses of DITA should reflect the
best of minimalist practice, for DITA to be widely applied it must make
some allowance for the practical challenges of legacy data and the sheer
cost involved in migrating a large existing body of documents and
established authoring practice to an often radically different way of
doing things.
And again I must apologize for raising these issues now and not a year
ago--it's just an accident of my personal work history that I didn't
have the opportunity to address these sorts of issues in a real context
before now. I'm definitely not suggesting we change the DITA model at
this time, but I think we still have time to tighten the spec as written
and prepare for more in-depth discussions in the 1.3/2.0 time frame.
But I think these questions also reflect the nature of the original DITA
definition, which was not intended to be anything like a formal standard
but to document the basics for a body of authors who shared a common
culture and for whom a lot of the DITA wisdom and knowledge was received
from collegues. By contrast, DITA the standard is a formal standard and
needs to, as much as possible, stand alone. I know we can't expect
something as legalistically formal as a Goldfarb standard in the 1.1
time frame (Michael is human, after all) but we still need to try to
make it as clear and precise as we can.
Cheers,
Eliot
--
W. Eliot Kimber
Professional Services
Innodata Isogen
9390 Research Blvd, #410
Austin, TX 78759
(214) 954-5198
ekimber@innodata-isogen.com
www.innodata-isogen.com