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] Re: Comparison between DITA and S1000D

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

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

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