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

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



  
-----Original Message----- 
From: Erik Hennum 
  [mailto:] 
Sent: Sat 8/28/2004 10:00 AM 
  
To: W. Eliot Kimber 
Cc: ; 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" 
  <> wrote on 08/26/2004 08:43:34 
  AM:

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