|
TC:
Thank you, Erik, for articulating the issue of granularity. If I were to
analysis the S1000D design, I would ask to what extent it already has
well-articulated content types, albeit defined within a larger document
structure. In many cases, I find that the content types in a complex, deep
structure are not well-defined in fact, although they may have been intended by
the original designers. The issue of "in fact" has to do with the complexity
introduced by the content creators, who often incompletely understand the
original design and are also not challenged by editorial experts charged with
maintaining the original design.
As a result, we see interwoven complexity in the content, often to the
detriment of the reader/user of the content.
By articulating a simple topic-based architecture, and enforcing it through
a topic-based technology, we hope to avoid the problem of complex, deep
structure that presents no advantage to the reader. One wonders if some of the
content creators have not studied Joyce's Ulysees in their interest in weaving
an interconnected story. We must keep in mind the manner in which users access
technical content, which is more likely to be at the topic level, unless the
content itself is so compelling to encourage in-depth reading for knowledge,
rather than reading for task completion that we so frequently see.
I would suggest that the DITA structure better supports the research on how
users work with technical information, than does the structure that actually
appears in documents based on a deeply nested structure.
JoAnn
joann.hackos@comtech-serv.com
-----Original Message-----
From: Erik Hennum
[mailto:ehennum@us.ibm.com]
Sent: Sat 8/28/2004 10:00 AM
To: W. Eliot Kimber
Cc: dita@lists.oasis-open.org; Tsao,
Scott; John Hunt
Subject: Re: [dita] Re: Comparison between DITA
and S1000D
Regarded TC:
Thanks, Eliot, for once again helping to drive the
crisp articulation of DITA by pushing on key issues.
As a topic
architecture, DITA doesn't permit deep structure within any one topic (no
nesting of sections). Instead, to realize deep structures, the content nests
different kinds of topics. Topic nesting can occur statically within a single
file or by reference through a map. Topic types can be designed for such
nesting.
For instance, to document an API library, we might have
separate topic types for the classes, methods, and parameters. In document
instances, the class topics would contain method topics, which in turn would
contain parameter topics. Thus, in document instances, the content structure
could be quite deep and complex, but the individual units of the structure are
relatively simple and shallow.
At the instance level, topic granularity
enables reuse of content. In the example, I could reuse a parameter topic
within different methods or even, if approapriate, reuse a method topic with
different parameter topics and within different class topics. What makes reuse
possible is splitting up the content into self-contained units.
Topic
granularity also has significant benefits at the design level. The topic
architecture simplifies design because it isolates each topic type as a
separate, small design problem. That makes the design easier to create and
evolve.
Again, the parallel is strong with Object Oriented Design. In
top-down structured programming, the entire program constituted one design
space. As a result, programs tended to become complex, deep logical structures
that were difficult to understand and maintain. By breaking up the program
structure into simple, granular objects and aggregating those objects to
create complex structures, designs became much more understandable, regular,
and maintainable.
So, returning to pre-existing document vocabularies
like S1000D, the design questions might be:
** Would a topic-based
architecture have benefits for the content? That is, would topic granularity,
content reuse, and modular design extensibility and pluggability have benefits
for the problem domain?
** If the content is suitable for a topic-based
architecture, could the model be based on the DITA topic? If so, the benefits
of a common type hierarchy can be realized.
Beyond the pure design
issues, of course, there are pragmatic questions such as migration cost,
community acceptance, and so on.
A possible strategy for coexistence
and interoperability between a well-established vocabulary and a topic model
would be to create a compatibility specialization. In this approach, the
designer would design topic types that best represent the content as usual.
Whenever possible, however, the designer would draw on elements from the
existing vocabulary for the names and substructure of topic types.
The
result will have integrity as a topic design and can participate in the common
DITA type hierarchy with all the benefits that ensue. In addition, however,
the compatibility specialization will be recognizable for users of the
existing vocabulary. Transforms to and from the existing vocabulary will also
be easier to write. (For what it's worth, in our experience, it has been much
easier to transform topic content into document content than in the reverse
direction because it's straightforward to assemble topics into a continuous
discourse.)
I don't think the DITA TC would be likely to undertake the
work of defining such a compatibility specialization for S1000D, but (after
DITA 1.0) the TC might take an interest in better understanding the
architectural issues for applying the topic architecture to new content
domains.
Good issues,
Erik
Hennum
ehennum@us.ibm.com
"W. Eliot Kimber"
<ekimber@innodata-isogen.com> wrote on 08/26/2004 08:43:34
AM:
> john_hunt@us.ibm.com wrote:
> >
> > Yes, I
agree. If there's potential to S1000D in adopting the DITA
> >
architecture, then the DITA-ized S1000D would develop a type hierarchy
> > with a base type. The question then becomes, why not start with
the DITA
> > base type? If not the DITA base type, then what's
needed in the DITA
> > base type to make it work?
> >
> > The advantages that ensue from a common base type are
significant. It's
> > this "specialization with a fallback" that
enables much of the power of
> > DITA's topic-based reuse model, and
which distinguishes it from other
> > approaches....
>
> This is a laudable goal but I think that it's important to keep a
couple
> of things in mind:
>
> 1. The DITA modules as
currently defined are not suitable as the base
> for this sort of very
wide use as the underpinnings for technical
> documentation. This is
because the current modules are too narrow in
> their constraints. For
example, none of the DTDs I use in my daily work
> for creating
technical documents can be directly derived from DITA
> because I use
(and want) more levels of containment than DITA can
> provide for. This
will be true for almost any DTD I have had a hand in
>
designing....
|