OASIS Darwin Information Typing Architecture (DITA) TC

  • 1.  Re: [dita] What Is A Topic

    Posted 12-21-2006 16:57
    Michael Priestley wrote:
    
    > On the issue of title-only topics in particular I wanted to add a few 
    > things:
    > 
    > - a small topic may legitimately need only a title and short description 
    > - our own glossentry specialization comes to mind. Some forms of 
    > context-sensitive help are also likely to be very short, and with the 
    > addition of abstract, easily accomodated without the  element.
    
    Hmmm--I'll have to think about this more.
    
    > - a topic may start small and grow over time into a whole branch of 
    > topics. The container topic may be no more than a title and child links 
    > (or just a title, with child links managed via a map). But the container 
    > topic is still important as a link destination, because it still answers 
    > the question it originally answered when it was just a leaf-node topic. 
    >  People who link to the topic shouldn't be forced to recode or break 
    > their links just because the topic has changed from leaf node to 
    > container node. In terms of its subject, it's still the same topic.
    
    This suggests to me that a different structure is needed rather than 
    trying to have topic do double duty as both a coherent direct container 
    of content and as simply a titled container.
    
    For example, I'm starting to think that it would make sense to allow 
    topichead wherever topic is currently allowed (possibly with a bit of 
    augmentation). This works well in maps so why not allow it in topics as 
    well? [But then would what it mean to have a document whose root element 
    is topichead--not sure and I can imagine that Michael would immediately 
    object to the possibility, which probably he should.]
    
    On the other hand, I could easily accept Michael's more flexible concept 
    of topic if we, as he suggests, add some discussion of how these two 
    different uses of topic are intended to be used and what would likely 
    constitute abuse of them.
    
    Clarifying question: When you say:
    
    "The container topic may be no more than a title and child links"
    
    Do you mean using links from the related-links section with a semantic 
    of "child"?
    
    I ask because topic does not allow topicref where it allows nested 
    topics (I originally expected them to be allowed) so I'm assuming that 
    related links is the intended way to create explicit hierarchical 
    relationships from within a topic to other topics. But then that raises 
    the issue of there being three distinct ways to do it (with a map using 
    topicrefs, with links, and with nested topics)--which approach do you 
    choose when?
    
    This question is somewhat driven by a question related to "what is a 
    topic" which is "when do I use a map to express a unit of re-use 
    (composed of a set of topics that don't have any real individual 
    meaning) and when do I use a topic with nested topics?"
    
    That is, the implication of Michael's reasoning for having title-only 
    topics that then just point to other topics is that they serve as a 
    consistently-available link target, which is definitely good. But given 
    that I could do the same thing with a map and topichead, which *should* 
    I do?
    
    If I say "use maps for all collecting of topics" then it leads to the 
    conclusion that there is a very real sense in which the map and the 
    equivalent title-only topic are serving exactly the same rhetorical and 
    practical purpose, which then suggests that either there's a need for a 
    different kind of map that is really a specialization of topic or something.
    
    But I do keep coming back to the possibility that the distinction 
    between maps and bodyless topics is very slight and that perhaps it 
    would make sense to unify them by allowing topic to allow topichead and 
    topicref where it currently allows nested topics.
    
    I also think that Michael's use case of a topic evolving from being a 
    singular chunk of information to the root of a tree of related topics is 
    a compelling one--it seems not only likely but inevitable.
    
    However, I'm not convinced that the right solution is simply keeping the 
    original topic around as a navigation target--given an appropriate 
    indirection mechanism (and corrected addressing scheme) you could just 
    as easily replace the original topic with a map (I can't do that today 
    because the *syntax and semantics* for addressing maps and topics is 
    different even though they probably shouldn't be).
    
    That is, maybe there are really two distinct types of maps: maps that 
    define entire units of delivery and maps that define units of re-use 
    that are functionally equivalent to topics with tested topics and/or 
    topics with child links to other topics.
    
    To my mind, it certainly seems intuitive to use maps for all organizing 
    of topics and it makes sense from a consistency of tools and work 
    practice, but it doesn't, at the moment, seem to fit as well as it could 
    or should with the current markup design. Thus my quandary.
    
    So I think there's definitely room for refinement in our collective 
    understanding in how to best address these issues of representation of 
    collections of topics that form coherent (and necessary) hierarchies in 
    order to convey a single "true" topic.
    
    Cheers,
    
    Eliot
    
    -- 
    W. Eliot Kimber
    Professional Services
    Innodata Isogen
    9390 Research Blvd, #410
    Austin, TX 78759
    (214) 954-5198
    
    ekimber@innodata-isogen.com
    www.innodata-isogen.com
    
    


  • 2.  RE: [dita] What Is A Topic

    Posted 12-27-2006 23:38
    I am about to start a new project for a client that has a lot of legacy API
    docs that they want converted to DITA. Since I wrote some of these docs I
    know there are many places where reuse can be effective. 
    
    The areas for reuse involves things like parameter descriptions and certain
    use notes. Neither of these would conventionally be thought of as topics. In
    DITA would it be best to treat them as topics even though some would not
    have a title.
    
    Rob
    


  • 3.  Re: [dita] What Is A Topic

    Posted 12-29-2006 16:21
    
    
      
      
    
    
    Personally, I'd like to see the definition of topic
    beefed up and kept in the standard, rather than watered down and
    demoted to a best practice merely.

    One of DITA's prime distinctions is being a topic-oriented DTD, as opposed to, say, DocBook. Remove that, and you muddy its distinctiveness.

    On the other hand, I agree with Eliot that inconsistencies have developed between nested topics and maps.

    Perhaps nested topics should be deprecated, and maps promoted as the preferred means to collect hierarchies of topics.

    If particular organizations still want to use DITA against the grain - well, there are always ways to accomplish that.

    Happy New Year!

    --Dana

    W. Eliot Kimber wrote:
    Michael Priestley wrote:

    On the issue of title-only topics in particular I wanted to add a few things:

    - a small topic may legitimately need only a title and short description - our own glossentry specialization comes to mind. Some forms of context-sensitive help are also likely to be very short, and with the addition of abstract, easily accomodated without the <body> element.

    Hmmm--I'll have to think about this more.

    - a topic may start small and grow over time into a whole branch of topics. The container topic may be no more than a title and child links (or just a title, with child links managed via a map). But the container topic is still important as a link destination, because it still answers the question it originally answered when it was just a leaf-node topic.  People who link to the topic shouldn't be forced to recode or break their links just because the topic has changed from leaf node to container node. In terms of its subject, it's still the same topic.

    This suggests to me that a different structure is needed rather than trying to have topic do double duty as both a coherent direct container of content and as simply a titled container.

    For example, I'm starting to think that it would make sense to allow topichead wherever topic is currently allowed (possibly with a bit of augmentation). This works well in maps so why not allow it in topics as well? [But then would what it mean to have a document whose root element is topichead--not sure and I can imagine that Michael would immediately object to the possibility, which probably he should.]

    On the other hand, I could easily accept Michael's more flexible concept of topic if we, as he suggests, add some discussion of how these two different uses of topic are intended to be used and what would likely constitute abuse of them.

    Clarifying question: When you say:

    "The container topic may be no more than a title and child links"

    Do you mean using links from the related-links section with a semantic of "child"?

    I ask because topic does not allow topicref where it allows nested topics (I originally expected them to be allowed) so I'm assuming that related links is the intended way to create explicit hierarchical relationships from within a topic to other topics. But then that raises the issue of there being three distinct ways to do it (with a map using topicrefs, with links, and with nested topics)--which approach do you choose when?

    This question is somewhat driven by a question related to "what is a topic" which is "when do I use a map to express a unit of re-use (composed of a set of topics that don't have any real individual meaning) and when do I use a topic with nested topics?"

    That is, the implication of Michael's reasoning for having title-only topics that then just point to other topics is that they serve as a consistently-available link target, which is definitely good. But given that I could do the same thing with a map and topichead, which *should* I do?

    If I say "use maps for all collecting of topics" then it leads to the conclusion that there is a very real sense in which the map and the equivalent title-only topic are serving exactly the same rhetorical and practical purpose, which then suggests that either there's a need for a different kind of map that is really a specialization of topic or something.

    But I do keep coming back to the possibility that the distinction between maps and bodyless topics is very slight and that perhaps it would make sense to unify them by allowing topic to allow topichead and topicref where it currently allows nested topics.

    I also think that Michael's use case of a topic evolving from being a singular chunk of information to the root of a tree of related topics is a compelling one--it seems not only likely but inevitable.

    However, I'm not convinced that the right solution is simply keeping the original topic around as a navigation target--given an appropriate indirection mechanism (and corrected addressing scheme) you could just as easily replace the original topic with a map (I can't do that today because the *syntax and semantics* for addressing maps and topics is different even though they probably shouldn't be).

    That is, maybe there are really two distinct types of maps: maps that define entire units of delivery and maps that define units of re-use that are functionally equivalent to topics with tested topics and/or topics with child links to other topics.

    To my mind, it certainly seems intuitive to use maps for all organizing of topics and it makes sense from a consistency of tools and work practice, but it doesn't, at the moment, seem to fit as well as it could or should with the current markup design. Thus my quandary.

    So I think there's definitely room for refinement in our collective understanding in how to best address these issues of representation of collections of topics that form coherent (and necessary) hierarchies in order to convey a single "true" topic.

    Cheers,

    Eliot



  • 4.  Re: [dita] What Is A Topic

    Posted 01-02-2007 21:26

    Hi, Esteemed TC:

    If we deprecate nested topics, that's going to force a rewrite of the API Reference and Java API Reference specializations, which use nested topics to model descriptions of methods of classes (among other things). We'd be forced to move the descriptions of methods into separate files, which would be counterintuitive for an API writer. Because a Java method always resides within one and only one class, it makes sense to nest the description of the method within the description of the class.

    More generally, there are probably other cases in which the subject matter dictates a primary hierarchy and primary reuse as a unit (so that it makes sense to author the topics as a single bundle). Shouldn't DITA be able to handle those exception cases as well as strongly encourage the best practice of reusable individual topics for the more common case?

    On the general point of section nesting, I wonder if it would be useful to compare an abstract example of nesting via section

    <topic id="a1">
    .... <title>A1 title</title>
    .... <body>
    ........ <p>A1 content</p>
    ........ <section id="b1">
    ............ <title>B1 title</title>
    ............ <p>B1 content</p>
    ............ <section id="c1">
    ................ <title>C1 title</title>
    ................ <p>C1 content</p>
    ............ </section>
    ........ </section>
    ........ <section id="b2">
    ............ <title>B2 title</title>
    ............ <p>B2 content</p>
    ........ </section>
    .... </body>
    </topic>

    with the equivalent nesting via topic

    <topic id="a1">
    .... <title>A1 title</title>
    .... <body>
    ........ <p>A1 content</p>
    .... </body>
    .... <topic id="b1">
    ........ <title>B1 title</title>
    ........ <body>
    ............ <p>B1 content</p>
    ........ </body>
    ........ <topic id="c1">
    ............ <title>C1 title</title>
    ............ <body>
    ................ <p>C1 content</p>
    ............ </body>
    ........ </topic>
    .... </topic>
    .... <topic id="b2">
    ........ <title>B2 title</title>
    ........ <body>
    ............ <p>B2 content</p>
    ........ </body>
    .... </topic>
    </topic>

    The content can fit into either markup without loss of structure or processing capability.

    The first markup, however, encourages the writer to view the structure as subdivisions within a continuous flow for a single unit of content.

    The second markup fights against that, encouraging the writer to view the substructure as distinct units of content.

    The question is whether that's the optimal blend of purist and pragmatist -- encouraging the best practice but allowing compromises because we live in the real world.

    Finally, a particular comment:

    "W. Eliot Kimber" <ekimber@innodata-isogen.com> wrote on 12/21/2006 08:57:04 AM:
    >

    > I ask because topic does not allow topicref where it allows nested
    > topics (I originally expected them to be allowed) so I'm assuming that
    > related links is the intended way to create explicit hierarchical
    > relationships from within a topic to other topics. But then that raises
    > the issue of there being three distinct ways to do it (with a map using
    > topicrefs, with links, and with nested topics)--which approach do you
    > choose when?


    FWIW, there is an existing proposal to introduce <topicref> as an alternative to <link> (deprecating the latter) so we get down to two:

    http://www.oasis-open.org/apps/org/workgroup/dita/download.php/14060/Issue37.html

    The existing proposal provides an account for handling topics with multiple hierarchy contexts but needs a bit more for reltables (maybe just a list of <relrow> in addition to <relcontext>).

    The primary concern raised in prior discussions of that proposal was revision to existing processing in the DITA Open Toolkit.


    Hoping that's useful (and that the New Year is very good to you),


    Erik Hennum
    ehennum@us.ibm.com



  • 5.  Re: [dita] What Is A Topic

    Posted 01-02-2007 22:46
    
    
      
      
    
    
    That's interesting, Erik.

    Are these specializations available for download from IBM? I don't see them in the toolkit.

    If I may inquire, what prompted the decision to use nested topics, instead of nested sections, in programming class topics to handle methods of that class?

    As you indicate, they don't really make sense as separate topics.

    --Dana

    Erik Hennum wrote:

    Hi, Esteemed TC:

    If we deprecate nested topics, that's going to force a rewrite of the API Reference and Java API Reference specializations, which use nested topics to model descriptions of methods of classes (among other things). We'd be forced to move the descriptions of methods into separate files, which would be counterintuitive for an API writer. Because a Java method always resides within one and only one class, it makes sense to nest the description of the method within the description of the class.

    More generally, there are probably other cases in which the subject matter dictates a primary hierarchy and primary reuse as a unit (so that it makes sense to author the topics as a single bundle). Shouldn't DITA be able to handle those exception cases as well as strongly encourage the best practice of reusable individual topics for the more common case?

    On the general point of section nesting, I wonder if it would be useful to compare an abstract example of nesting via section

    <topic id="a1">
    .... <title>A1 title</title>
    .... <body>
    ........ <p>A1 content</p>
    ........ <section id="b1">
    ............ <title>B1 title</title>
    ............ <p>B1 content</p>
    ............ <section id="c1">
    ................ <title>C1 title</title>
    ................ <p>C1 content</p>
    ............ </section>
    ........ </section>
    ........ <section id="b2">
    ............ <title>B2 title</title>
    ............ <p>B2 content</p>
    ........ </section>
    .... </body>
    </topic>

    with the equivalent nesting via topic

    <topic id="a1">
    .... <title>A1 title</title>
    .... <body>
    ........ <p>A1 content</p>
    .... </body>
    .... <topic id="b1">
    ........ <title>B1 title</title>
    ........ <body>
    ............ <p>B1 content</p>
    ........ </body>
    ........ <topic id="c1">
    ............ <title>C1 title</title>
    ............ <body>
    ................ <p>C1 content</p>
    ............ </body>
    ........ </topic>
    .... </topic>
    .... <topic id="b2">
    ........ <title>B2 title</title>
    ........ <body>
    ............ <p>B2 content</p>
    ........ </body>
    .... </topic>
    </topic>

    The content can fit into either markup without loss of structure or processing capability.

    The first markup, however, encourages the writer to view the structure as subdivisions within a continuous flow for a single unit of content.

    The second markup fights against that, encouraging the writer to view the substructure as distinct units of content.

    The question is whether that's the optimal blend of purist and pragmatist -- encouraging the best practice but allowing compromises because we live in the real world.

    Finally, a particular comment:

    "W. Eliot Kimber" <ekimber@innodata-isogen.com> wrote on 12/21/2006 08:57:04 AM:
    >

    > I ask because topic does not allow topicref where it allows nested
    > topics (I originally expected them to be allowed) so I'm assuming that
    > related links is the intended way to create explicit hierarchical
    > relationships from within a topic to other topics. But then that raises
    > the issue of there being three distinct ways to do it (with a map using
    > topicrefs, with links, and with nested topics)--which approach do you
    > choose when?


    FWIW, there is an existing proposal to introduce <topicref> as an alternative to <link> (deprecating the latter) so we get down to two:

    http://www.oasis-open.org/apps/org/workgroup/dita/download.php/14060/Issue37.html

    The existing proposal provides an account for handling topics with multiple hierarchy contexts but needs a bit more for reltables (maybe just a list of <relrow> in addition to <relcontext>).

    The primary concern raised in prior discussions of that proposal was revision to existing processing in the DITA Open Toolkit.


    Hoping that's useful (and that the New Year is very good to you),


    Erik Hennum
    ehennum@us.ibm.com



  • 6.  Re: [dita] What Is A Topic

    Posted 01-02-2007 23:45

    Hi, Dana:

    The API Reference and Java API Reference specializations are in fact available on the Open Toolkit site, but you're not at fault for missing them. You have to go to the "Plug-ins: specializations" section and click on the link for "View older releases from the Plug-ins: specializations package" The current web UI only accomodates 3 plugins, but I understand that can be changed (which is pretty important for the plugin contributors). The Java API depends on the API Reference specialization, by the way.

    Anyway, regarding the substance -- there was a fit with existing practice: a JavaDoc description of a method typically stands alone as a highly linked target. In the implementation, the method descriptions were quite convenient to model as topics (the same basic structure applies to both class and method descriptions). Supplementing the API relationships with map-based management of related links (and, one hopes, DITA 1.2 implicit linking based on mentions of keywords and terms) are other good reasons.

    But, while method descriptions seem a good fit for topics, they wouldn't work as well as _separate_ topics in the sense of separate files assembled by a map -- largely because the subject matter (a Java class) has a single nesting structure that's a stable unit.


    Hoping that's useful,


    Erik Hennum
    ehennum@us.ibm.com


    Dana Spradley <dana.spradley@oracle.com> wrote on 01/02/2007 02:45:56 PM:
    >
    > Are these specializations available for download from IBM? I don't
    > see them in the toolkit.
    >
    > If I may inquire, what prompted the decision to use nested topics,
    > instead of nested sections, in programming class topics to handle
    > methods of that class?
    >
    > As you indicate, they don't really make sense as separate topics.



  • 7.  Re: [dita] What Is A Topic

    Posted 01-03-2007 00:07
    
    
      
      
    
    
    Well yes Erik, I can see that.

    It makes sense that reference topic types might require a richer assortment of nesting structures that mimic the well-defined hierarchical arrangement of their subject matter.

    Perhaps one could merely deprecate nesting tasks inside tasks, or concepts inside concepts.

    As I recall, minimalist topic orientation was invented to move away from the highly nested, lengthily belabored discursive structures that reference material often requires.

    On the other hand, I personally might have no objection to a topic that was only a title, with no elaboration, if we considered doing that to remove the inconsistencies with maps Eliot has pointed out.

    Sometimes the title really does say it all.

    --Dana

    Erik Hennum wrote:

    Hi, Dana:

    The API Reference and Java API Reference specializations are in fact available on the Open Toolkit site, but you're not at fault for missing them. You have to go to the "Plug-ins: specializations" section and click on the link for "View older releases from the Plug-ins: specializations package" The current web UI only accomodates 3 plugins, but I understand that can be changed (which is pretty important for the plugin contributors). The Java API depends on the API Reference specialization, by the way.

    Anyway, regarding the substance -- there was a fit with existing practice: a JavaDoc description of a method typically stands alone as a highly linked target. In the implementation, the method descriptions were quite convenient to model as topics (the same basic structure applies to both class and method descriptions). Supplementing the API relationships with map-based management of related links (and, one hopes, DITA 1.2 implicit linking based on mentions of keywords and terms) are other good reasons.

    But, while method descriptions seem a good fit for topics, they wouldn't work as well as _separate_ topics in the sense of separate files assembled by a map -- largely because the subject matter (a Java class) has a single nesting structure that's a stable unit.


    Hoping that's useful,


    Erik Hennum
    ehennum@us.ibm.com


    Dana Spradley <dana.spradley@oracle.com> wrote on 01/02/2007 02:45:56 PM:
    >
    > Are these specializations available for download from IBM? I don't
    > see them in the toolkit.
    >
    > If I may inquire, what prompted the decision to use nested topics,
    > instead of nested sections, in programming class topics to handle
    > methods of that class?
    >
    > As you indicate, they don't really make sense as separate topics.