Re: [dita] Re: Comparison between DITA and S1000D

[Erik Hennum <ehennum@us.ibm.com>]

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