[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: [no subject]
I would definitely endorse the idea of documenting the findings in a
separate "best practices" document, in terms of "a consistent approach
to addressing relationships between DITA and other topic-based
standards." And, if possible, provide an example based on the S1000D
spec. In this respect, I could probably solicit help from my colleagues
who are experts in the S1000D domain.
=20
Best regards,
Scott Tsao=20
The Boeing Company=20
P.O. Box 3707, MC 67-EF=20
Seattle, WA 98124-2207=20
425-234-3761=20
scott.tsao@boeing.com
-----Original Message-----
From: JoAnn Hackos [mailto:JoAnn.Hackos@Comtech-Serv.com]=20
Sent: Tuesday, August 31, 2004 6:21 AM
To: Erik Hennum; W. Eliot Kimber
Cc: dita@lists.oasis-open.org; Tsao, Scott; John Hunt
Subject: RE: [dita] Re: Comparison between DITA and S1000D
=09
=09
TC:
=20
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.
=20
As a result, we see interwoven complexity in the content, often
to the detriment of the reader/user of the content.=20
=20
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.
=20
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.
=20
JoAnn
joann.hackos@comtech-serv.com
-----Original Message-----=20
From: Erik Hennum [mailto:ehennum@us.ibm.com]=20
Sent: Sat 8/28/2004 10:00 AM=20
To: W. Eliot Kimber=20
Cc: dita@lists.oasis-open.org; Tsao, Scott; John Hunt=20
Subject: Re: [dita] Re: Comparison between DITA and
S1000D
=09
=09
Regarded TC:
=09
Thanks, Eliot, for once again helping to drive the crisp
articulation of DITA by pushing on key issues.
=09
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.=20
=09
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.
=09
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.
=09
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.
=09
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.
=09
So, returning to pre-existing document vocabularies like
S1000D, the design questions might be:
=09
** 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?
=09
** 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.
=09
Beyond the pure design issues, of course, there are
pragmatic questions such as migration cost, community acceptance, and so
on.
=09
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.
=09
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.)
=09
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.
=09
=09
Good issues,
=09
=09
Erik Hennum
ehennum@us.ibm.com
=09
=09
"W. Eliot Kimber" <ekimber@innodata-isogen.com> wrote on
08/26/2004 08:43:34 AM:
=09
> john_hunt@us.ibm.com wrote:
> >=20
> > Yes, I agree. If there's potential to S1000D in
adopting the DITA=20
> > architecture, then the DITA-ized S1000D would
develop a type hierarchy=20
> > with a base type. The question then becomes, why not
start with the DITA=20
> > base type? If not the DITA base type, then what's
needed in the DITA=20
> > base type to make it work?
> >=20
> > The advantages that ensue from a common base type
are significant. It's=20
> > this "specialization with a fallback" that enables
much of the power of=20
> > DITA's topic-based reuse model, and which
distinguishes it from other=20
> > approaches....
>=20
> This is a laudable goal but I think that it's
important to keep a couple=20
> of things in mind:
>=20
> 1. The DITA modules as currently defined are not
suitable as the base=20
> for this sort of very wide use as the underpinnings
for technical=20
> documentation. This is because the current modules are
too narrow in=20
> their constraints. For example, none of the DTDs I use
in my daily work=20
> for creating technical documents can be directly
derived from DITA=20
> because I use (and want) more levels of containment
than DITA can=20
> provide for. This will be true for almost any DTD I
have had a hand in=20
> designing....
=09
------_=_NextPart_001_01C496C2.71C254E0
Content-Type: text/html;
charset="us-ascii"
Content-Transfer-Encoding: quoted-printable
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML><HEAD><TITLE>Message</TITLE>
<META http-equiv=3DContent-Type content=3D"text/html; =
charset=3Dus-ascii">
<META content=3D"MSHTML 6.00.2800.1400" name=3DGENERATOR></HEAD>
<BODY dir=3Dltr>
<DIV><FONT face=3DArial color=3D#0000ff size=3D2><SPAN =
class=3D305105922-09092004>I am=20
deeply indebted to the TC members/observers who spent a great deal of =
time=20
sharing their views on this interesting and important=20
subject.</SPAN></FONT></DIV>
<DIV><FONT face=3DArial color=3D#0000ff size=3D2><SPAN=20
class=3D305105922-09092004></SPAN></FONT> </DIV>
<DIV><FONT face=3DArial color=3D#0000ff size=3D2><SPAN =
class=3D305105922-09092004>From=20
this week's meeting minutes:</SPAN></FONT></DIV>
<DIV><FONT face=3DArial color=3D#0000ff size=3D2><SPAN=20
class=3D305105922-09092004></SPAN></FONT> </DIV>
<DIV><FONT face=3DArial color=3D#0000ff size=3D2><SPAN=20
class=3D305105922-09092004> - =
Comparison=20
between DITA and S1000D--any further=20
actions?<BR> &=
nbsp; -=20
JoAnn -- Without Scott on the phone, how do we=20
resolve<BR> &n=
bsp; =20
this? (Scott is the one who originated=20
the<BR> =
=20
discussion.) =20
<BR> - =
Don --=20
Perhaps at this point we should just draft=20
some<BR>  =
; =20
comments saying that there are relationships=20
between<BR> &n=
bsp; =20
DITA and other topic-based=20
architectures?<BR> &=
nbsp; =20
- Erik -- Perhaps we should come up with a=20
consistent<BR>  =
; =20
approach to addressing relationships between DITA=20
and<BR> =
=20
other topic-based standards -- not just focused=20
on<BR> &=
nbsp; =20
S1000D.<BR> &n=
bsp; -=20
Seraphim -- Let's include this in the "best=20
practices"<BR>  =
; =20
doc that accompanies the spec -- not in the=20
spec<BR>  =
; =20
itself.<BR> &n=
bsp; -=20
Don -- Let's make this a formal recommendation=20
(future<BR> &n=
bsp; =20
agenda item?), to create a "best practices"=20
document<BR> &=
nbsp; =20
separate from the spec. We will include=20
the<BR> =
=20
discussion on other topic-based standards in=20
this<BR>  =
; =20
"best practices" doc.<BR></SPAN></FONT></DIV>
<DIV><FONT face=3DArial color=3D#0000ff size=3D2><SPAN =
class=3D305105922-09092004>I=20
would definitely endorse the idea of documenting the findings in a =
separate=20
"best practices" document, in terms of "a consistent approach to =
addressing=20
relationships between DITA and other topic-based standards." And, =
if=20
possible, provide an example based on the S1000D spec. In this =
respect, I=20
could probably solicit help from my colleagues who are experts in the =
S1000D=20
domain.</SPAN></FONT></DIV>
<DIV><FONT face=3DArial color=3D#0000ff size=3D2><SPAN=20
class=3D305105922-09092004></SPAN></FONT> </DIV>
<DIV><FONT face=3DArial color=3D#0000ff size=3D2><SPAN =
class=3D305105922-09092004>Best=20
regards,</SPAN></FONT></DIV>
<DIV><FONT face=3DArial color=3D#0000ff size=3D2><SPAN =
class=3D305105922-09092004><!-- Converted from text/rtf format -->
<DIV align=3Dleft><FONT face=3DArial size=3D2></FONT><BR></DIV>
<P><B><I><FONT face=3D"MS Sans Serif" color=3D#ff0000 size=3D2>Scott=20
Tsao</FONT></I></B> <BR><FONT face=3D"MS Sans Serif" size=3D2>The Boeing =
Company</FONT> <BR><FONT face=3D"MS Sans Serif" size=3D2>P.O. Box 3707, =
MC=20
6</FONT><FONT face=3D"MS Sans Serif" size=3D2>7-EF</FONT> <BR><FONT=20
face=3D"MS Sans Serif" size=3D2>Seattle, WA 98124-2207</FONT> <BR><FONT=20
face=3D"MS Sans Serif" size=3D2>425</FONT><FONT face=3D"MS Sans Serif"=20
size=3D2>-</FONT><FONT face=3DArial size=3D2>234-3761</FONT> <BR><FONT=20
face=3D"MS Sans Serif" size=3D2><A=20
href=3D"mailto:scott.tsao@boeing.com";>scott.tsao@boeing.com</A></FONT></P=
></DIV></SPAN></FONT>
<BLOCKQUOTE dir=3Dltr style=3D"MARGIN-RIGHT: 0px">
<DIV></DIV>
<DIV class=3DOutlookMessageHeader lang=3Den-us dir=3Dltr =
align=3Dleft><FONT=20
face=3DTahoma size=3D2>-----Original Message-----<BR><B>From:</B> =
JoAnn Hackos=20
[mailto:JoAnn.Hackos@Comtech-Serv.com] <BR><B>Sent:</B> Tuesday, =
August 31,=20
2004 6:21 AM<BR><B>To:</B> Erik Hennum; W. Eliot Kimber<BR><B>Cc:</B>=20
dita@lists.oasis-open.org; Tsao, Scott; John Hunt<BR><B>Subject:</B> =
RE:=20
[dita] Re: Comparison between DITA and S1000D<BR><BR></FONT></DIV>
<DIV>TC:</DIV>
<DIV> </DIV>
<DIV>Thank you, Erik, for articulating the issue of granularity. If I =
were to=20
analysis the S1000D design, I would ask to what extent it already has=20
well-articulated content types, albeit defined within a larger =
document=20
structure. In many cases, I find that the content types in a complex, =
deep=20
structure are not well-defined in fact, although they may have been =
intended=20
by the original designers. The issue of "in fact" has to do with the=20
complexity introduced by the content creators, who often incompletely=20
understand the original design and are also not challenged by =
editorial=20
experts charged with maintaining the original design.</DIV>
<DIV> </DIV>
<DIV>As a result, we see interwoven complexity in the content, often =
to the=20
detriment of the reader/user of the content. </DIV>
<DIV> </DIV>
<DIV>By articulating a simple topic-based architecture, and enforcing =
it=20
through a topic-based technology, we hope to avoid the problem of =
complex,=20
deep structure that presents no advantage to the reader. One wonders =
if some=20
of the content creators have not studied Joyce's Ulysees in their =
interest in=20
weaving an interconnected story. We must keep in mind the manner in =
which=20
users access technical content, which is more likely to be at the =
topic level,=20
unless the content itself is so compelling to encourage in-depth =
reading for=20
knowledge, rather than reading for task completion that we so =
frequently=20
see.</DIV>
<DIV> </DIV>
<DIV>I would suggest that the DITA structure better supports the =
research on=20
how users work with technical information, than does the structure =
that=20
actually appears in documents based on a deeply nested =
structure.</DIV>
<DIV> </DIV>
<DIV>JoAnn</DIV>
<DIV>joann.hackos@comtech-serv.com</DIV>
<BLOCKQUOTE dir=3Dltr style=3D"MARGIN-RIGHT: 0px">
<DIV><FONT size=3D2>-----Original Message----- <BR><B>From:</B> Erik =
Hennum=20
[mailto:ehennum@us.ibm.com] <BR><B>Sent:</B> Sat 8/28/2004 10:00 AM=20
<BR><B>To:</B> W. Eliot Kimber <BR><B>Cc:</B> =
dita@lists.oasis-open.org;=20
Tsao, Scott; John Hunt <BR><B>Subject:</B> Re: [dita] Re: Comparison =
between=20
DITA and S1000D<BR><BR></FONT></DIV>
<P>Regarded TC:<BR><BR>Thanks, Eliot, for once again helping to =
drive the=20
crisp articulation of DITA by pushing on key issues.<BR><BR>As a =
topic=20
architecture, DITA doesn't permit deep structure within any one =
topic (no=20
nesting of sections). Instead, to realize deep structures, the =
content nests=20
different kinds of topics. Topic nesting can occur statically within =
a=20
single file or by reference through a map. Topic types can be =
designed for=20
such nesting. <BR><BR>For instance, to document an API library, we =
might=20
have separate topic types for the classes, methods, and parameters. =
In=20
document instances, the class topics would contain method topics, =
which in=20
turn would contain parameter topics. Thus, in document instances, =
the=20
content structure could be quite deep and complex, but the =
individual units=20
of the structure are relatively simple and shallow.<BR><BR>At the =
instance=20
level, topic granularity enables reuse of content. In the example, I =
could=20
reuse a parameter topic within different methods or even, if =
approapriate,=20
reuse a method topic with different parameter topics and within =
different=20
class topics. What makes reuse possible is splitting up the content =
into=20
self-contained units.<BR><BR>Topic granularity also has significant =
benefits=20
at the design level. The topic architecture simplifies design =
because it=20
isolates each topic type as a separate, small design problem. That =
makes the=20
design easier to create and evolve.<BR><BR>Again, the parallel is =
strong=20
with Object Oriented Design. In top-down structured programming, the =
entire=20
program constituted one design space. As a result, programs tended =
to become=20
complex, deep logical structures that were difficult to understand =
and=20
maintain. By breaking up the program structure into simple, granular =
objects=20
and aggregating those objects to create complex structures, designs =
became=20
much more understandable, regular, and maintainable.<BR><BR>So, =
returning to=20
pre-existing document vocabularies like S1000D, the design questions =
might=20
be:<BR><BR>** Would a topic-based architecture have benefits for the =
content? That is, would topic granularity, content reuse, and =
modular design=20
extensibility and pluggability have benefits for the problem=20
domain?<BR><BR>** If the content is suitable for a topic-based =
architecture,=20
could the model be based on the DITA topic? If so, the benefits of a =
common=20
type hierarchy can be realized.<BR><BR>Beyond the pure design =
issues, of=20
course, there are pragmatic questions such as migration cost, =
community=20
acceptance, and so on.<BR><BR>A possible strategy for coexistence =
and=20
interoperability between a well-established vocabulary and a topic =
model=20
would be to create a compatibility specialization. In this approach, =
the=20
designer would design topic types that best represent the content as =
usual.=20
Whenever possible, however, the designer would draw on elements from =
the=20
existing vocabulary for the names and substructure of topic=20
types.<BR><BR>The result will have integrity as a topic design and =
can=20
participate in the common DITA type hierarchy with all the benefits =
that=20
ensue. In addition, however, the compatibility specialization will =
be=20
recognizable for users of the existing vocabulary. Transforms to and =
from=20
the existing vocabulary will also be easier to write. (For what it's =
worth,=20
in our experience, it has been much easier to transform topic =
content into=20
document content than in the reverse direction because it's =
straightforward=20
to assemble topics into a continuous discourse.)<BR><BR>I don't =
think the=20
DITA TC would be likely to undertake the work of defining such a=20
compatibility specialization for S1000D, but (after DITA 1.0) the TC =
might=20
take an interest in better understanding the architectural issues =
for=20
applying the topic architecture to new content =
domains.<BR><BR><BR>Good=20
issues,<BR><BR><BR>Erik =
Hennum<BR>ehennum@us.ibm.com<BR><BR><BR><TT>"W.=20
Eliot Kimber" <ekimber@innodata-isogen.com> wrote on =
08/26/2004=20
08:43:34 AM:<BR><BR>> john_hunt@us.ibm.com wrote:<BR>> > =
<BR>>=20
> Yes, I agree. If there's potential to S1000D in adopting the =
DITA=20
<BR>> > architecture, then the DITA-ized S1000D would develop =
a type=20
hierarchy <BR>> > with a base type. The question then becomes, =
why not=20
start with the DITA <BR>> > base type? If not the DITA base =
type, then=20
what's needed in the DITA <BR>> > base type to make it =
work?<BR>>=20
> <BR>> > The advantages that ensue from a common base type =
are=20
significant. It's <BR>> > this "specialization with a =
fallback" that=20
enables much of the power of <BR>> > DITA's topic-based reuse =
model,=20
and which distinguishes it from other <BR>> > =
approaches....<BR>>=20
<BR>> This is a laudable goal but I think that it's important to =
keep a=20
couple <BR>> of things in mind:<BR>> <BR>> 1. The DITA =
modules as=20
currently defined are not suitable as the base <BR>> for this =
sort of=20
very wide use as the underpinnings for technical <BR>> =
documentation.=20
This is because the current modules are too narrow in <BR>> their =
constraints. For example, none of the DTDs I use in my daily work =
<BR>>=20
for creating technical documents can be directly derived from DITA =
<BR>>=20
because I use (and want) more levels of containment than DITA can =
<BR>>=20
provide for. This will be true for almost any DTD I have had a hand =
in=20
<BR>> =
designing....<BR></TT></P></BLOCKQUOTE></BLOCKQUOTE></BODY></HTML>
------_=_NextPart_001_01C496C2.71C254E0--
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]