OASIS Darwin Information Typing Architecture (DITA) TC

  • 1.  Managing "contextless elements" as for L&T Assessments and Objectives

    Posted 11-28-2017 16:15
    One of the requirements that has emerged in the use of Learning and Training questions (interactions) is the need to manage individual questions as reusable objects through maps. The typical use case is constructing a test at the map level, rather than using conref. Using maps for this makes a lot more sense as pretty much all of the available DITA-aware tooling is optimized for map-based reuse rather than conref-based reuse at the sort of scale represented by a test. Imagine, for example, a test consisting of scores or hundreds of questions. Trying to manage that through conref becomes complicated and tedious, at least with typical authoring tools. This leads to a situation where we want to treat individual questions as though they were topics from a management and aggregation standpoint but the questions themselves are just elements within topics and would not be appropriately modeled as topics themselves (or example, most questions don’t have natural titles). All of us in the L&T community have struggled with this sort of topic/not-a-topic nature of questions (and to a lesser degree, learning objectives). For example, in the past I’ve defined a “question topic” specialization where the title is an empty element and the navigation title is required. This is a hack but it kind of works but it isn’t really ideal. In thinking about this more in the context of our latest L&T subcommittee discussions, I realized that L&T assessments are what I would call “contextless elements”, meaning elements that are not topics but that are fundamentally independent of any context. That is, an individual question is not normally dependent on the elements around it the way that say paragraphs or lists or even figures or tables are. Or maybe more usefully, questions do not contribute to any narrative flow—they are true objects intended to be combined arbitrarily with other questions. Learning objectives have the same quality—they do not contribute to any narrative flow and are intended to be used directly or indirectly to characterize different learning content. For example, it is useful to both use objectives by conref and to use more indirect association between objectives and learning objects, such as via reltable or subject scheme. I haven’t been able to think of any other kind of information that would have this “contextless” characteristic but it seems likely there are such things in other domains, so I think it’s useful to try to capture the abstraction. So if we accept this concept of “contextess elements” then my main question is what is the best way to enable their direct use via maps? In the case of creating a test, I want to construct a map where I have topics that represent the test as a whole, for example, to provide initial instructions, introductory material, examples, etc., and also to organize the questions hierarchically (imagine a typical standardized test with many sections and subsections) and then have references to questions where the referenced questions are treated as though they were part of the body content of the parent topic (as defined in the map) for presentation purposes. One possibility would be to define a new generic topic type of “contextless element container” which has the specific semantic of “this topic exists only to contain content that can be combined together arbitrarily and its title is not to be used in normal output”. That would essentially codify the “question topic” type that I’ve defined in the past. I think this is probably the most appropriate solution because it binds the semantic directly to the topic, rather than to references to it. Another approach would be to provide some way to say on the topicref “use the shortdesc, abstract, and body of this topic but don’t use the title”, making it clear that the intended presentation result is equivalent to having the same topic content occur in a single topic as though via conref. This is basically what people have been doing to date one way or another, but via private convention and custom processing. Yet another approach would be an architectural change that allows direct use of elements from maps, maybe using a new “elementref” element or something. I’m not necessarily suggesting this is a good idea, just enumerating the possibilities. This kind of element would raise a whole raft of issues around resolving references from the element to other things based on use context and so might require specific restrictions (for example, such elements must be the abstract or only body child of their containing topics). However, I know there is a latent desire to able to use map-style linking to create the effective content of topics rather than using conref within the topics, so maybe it’s worth considering if only to decide the complexity of the solution is too great. Cheers, E. -- Eliot Kimber http://contrext.com


  • 2.  RE: [dita] Managing "contextless elements" as for L&T Assessments and Objectives

    Posted 11-29-2017 16:18
      |   view attached
    Thanks for the summary, Eliot.   Although a single question is a unit that can be understood in isolation and used in multiple contexts, it doesn't meet the definition of a topic in that it does not natural title. This means that they fall into the gray area that you are calling “contextless elements”. I can't think of a better way to describe it and thank you for your suggested terminology.   Because assessment and learning objectives are fundamental to learning content, we are definitely going to address this issue on the L&T SC. However, we don't want to do this in isolation, so if you have grappled with content that meets the same criteria, please share your experience with the TC.   Many thanks, Amber      


  • 3.  Re: [dita] Managing "contextless elements" as for L&T Assessments and Objectives

    Posted 11-30-2017 14:40
    Hi Amber, Eliot, Isn't the generic DITA topic already quite contextless ? I thought that chunking was the way to use a topic without the title? I assume there is a title somewhere, just it is not required for the contextless topic. This seems like a parallel to Information mapping? I would be concerned if the proposed solution would be to put content in a map, and would suggest a wider discussion about what the role of a map and a topic should be, going forward. I appreciate that metadata in a map is already used for various purposes: reuse and subject schemes, for instance. But one of the potential solutions would seem to go further than that. I acknowledge Eliot's caveats about this potential solution. There might be a parallel with resource-only container topics , or warehouse topics that simply provide content for reuse. The topic itself never appears in the final document. My two penn'orth. HTH, David Thanks for the summary, Eliot.   Although a single question is a unit that can be understood in isolation and used in multiple contexts, it doesn't meet the definition of a topic in that it does not natural title. This means that they fall into the gray area that you are calling “contextless elements”. I can't think of a better way to describe it and thank you for your suggested terminology.   Because assessment and learning objectives are fundamental to learning content, we are definitely going to address this issue on the L&T SC. However, we don't want to do this in isolation, so if you have grappled with content that meets the same criteria, please share your experience with the TC.   Many thanks, Amber      


  • 4.  RE: [dita] Managing "contextless elements" as for L&T Assessments and Objectives

    Posted 11-30-2017 15:05
    While there are admittedly topic types where the title is not required for publishing, I think that every topic needs a label for identification and management purposes. The title plays a dual role as content and metadata (label). Could the solution be as easy as specializing a label element from title from some topic types where this is the case? I think label could be a useful substitution for title in any instance where the title is not needed for publication but still required for identification, such as sections and figures.   Cheers, Rob Hanna   From: dita@lists.oasis-open.org [mailto:dita@lists.oasis-open.org] On Behalf Of David Hollis Sent: Thursday, November 30, 2017 6:40 AM Cc: dita <dita@lists.oasis-open.org> Subject: Re: [dita] Managing "contextless elements" as for L&T Assessments and Objectives   Hi Amber, Eliot,   Isn't the generic DITA topic already quite "contextless"?   I thought that chunking was the way to use a topic without the title? I assume there is a title somewhere, just it is not required for the "contextless" topic. This seems like a parallel to Information mapping?   I would be concerned if the proposed solution would be to put content in a map, and would suggest a wider discussion about what the role of a map and a topic should be, going forward. I appreciate that metadata in a map is already used for various purposes: reuse and subject schemes, for instance. But one of the potential solutions would seem to go further than that. I acknowledge Eliot's caveats about this potential solution.   There might be a parallel with resource-only "container topics", or "warehouse topics" that simply provide content for reuse. The topic itself never appears in the final document.   My two penn'orth.   HTH, David   Thanks for the summary, Eliot.   Although a single question is a unit that can be understood in isolation and used in multiple contexts, it doesn't meet the definition of a topic in that it does not natural title. This means that they fall into the gray area that you are calling “contextless elements”. I can't think of a better way to describe it and thank you for your suggested terminology.   Because assessment and learning objectives are fundamental to learning content, we are definitely going to address this issue on the L&T SC. However, we don't want to do this in isolation, so if you have grappled with content that meets the same criteria, please share your experience with the TC.   Many thanks, Amber      


  • 5.  RE: [dita] Managing "contextless elements" as for L&T Assessments and Objectives

    Posted 11-30-2017 17:05
    Thanks for the notes, Rob and David.   Many companies need to manage questions a separate units, which means that the easiest way to assemble them in a deliverable is to have separate topics and then organize them with a map. This also allows you to apply different key value to different questions in the context of a map. The L&T SC has determined that storing the questions as separate units is a requirement we need to support.   As for the title discussion, I have not yet seen question title used for a publishing context. One could argue that the question stem may be relevant as a label for the topic, but question stems may be more than one paragraph and may be very generic. The real issue is that most folks don ??t have anything to use as a label for a given question. So, I have been considering this challenge from the perspective of how folks use the topics.   One of the primary use cases is assembling a collection of questions for a test. Because it is very common to have the same stem for multiple questions, the current out-of-the-box support in most editors is to display the title for the topic reference. This means that if you leave the title blank in the question topic, then the map is a list of nameless topic references. You essentially have to use a view with the resolved topics to know what you ??re building. In many cases the order of the references isn ??t important, but you need to know that you haven ??t included the same question multiple times. You may also need to apply key references to specific questions so it is imperative that you know which question is referenced.   For example, for a driver training course, you may have 500 topics with ??Who has the right of way in the following traffic pattern? ?? as the question stem. What would be the label or title for these topics? If I ??m assembling a map to test the learner ??s knowledge about the concept of right of way, I could have 50 of these question in a map. To associate the relevant learning objective to the topic, I need to know which questions apply to which learning objective.   When I consider the role that a title plays in this scenario, the issue is about what is displayed in the map rather than what is stored in the topic. I can think of several options to help with the display of relevant metadata is helpful, but none of them address the question of what, if anything, should be stored as the title or label of a question.   Eliot proposed three options in the original email. Although an option, I don ??t support the idea to directly use elements in the map. I ??d like to investigate the first two options and any others that folks can propose. If you have other options, please contribute your suggestions.   Have a great day, Amber         From: dita@lists.oasis-open.org [mailto: dita@lists.oasis-open.org ] On Behalf Of Rob Hanna Sent: Thursday, November 30, 2017 7:05 AM To: David Hollis Cc: dita Subject: RE: [dita] Managing "contextless elements" as for L&T Assessments and Objectives   While there are admittedly topic types where the title is not required for publishing, I think that every topic needs a label for identification and management purposes. The title plays a dual role as content and metadata (label). Could the solution be as easy as specializing a label element from title from some topic types where this is the case? I think label could be a useful substitution for title in any instance where the title is not needed for publication but still required for identification, such as sections and figures.   Cheers, Rob Hanna   From: dita@lists.oasis-open.org [ mailto:dita@lists.oasis-open.org ] On Behalf Of David Hollis Sent: Thursday, November 30, 2017 6:40 AM Cc: dita < dita@lists.oasis-open.org > Subject: Re: [dita] Managing "contextless elements" as for L&T Assessments and Objectives   Hi Amber, Eliot,   Isn't the generic DITA topic already quite "contextless"?   I thought that chunking was the way to use a topic without the title? I assume there is a title somewhere, just it is not required for the "contextless" topic. This seems like a parallel to  Information mapping?   I would be concerned if the proposed solution would be to put content in a map, and would suggest a wider discussion about what the role of a map and a topic should be, going forward. I appreciate that metadata in a map is already used for various purposes: reuse and subject schemes, for instance. But one of the potential solutions would seem to go further than that. I acknowledge Eliot's caveats about this potential solution.   There might be a parallel with resource-only "container topics", or "warehouse topics" that simply provide content for reuse. The topic itself never appears in the final document.   My two penn'orth.   HTH, David     Thanks for the summary, Eliot.   Although a single question is a unit that can be understood in isolation and used in multiple contexts, it doesn't meet the definition of a topic in that it does not natural title. This means that they fall into the gray area that you are calling ??contextless elements ??. I can't think of a better way to describe it and thank you for your suggested terminology.   Because assessment and learning objectives are fundamental to learning content, we are definitely going to address this issue on the L&T SC. However, we don't want to do this in isolation, so if you have grappled with content that meets the same criteria, please share your experience with the TC.   Many thanks, Amber      


  • 6.  Re: [dita] Managing "contextless elements" as for L&T Assessments and Objectives

    Posted 12-01-2017 10:18




    Rob’s example of figures brought to mind a kind of “contextless element” case that I dealt with previously. As it’s a non-L&T case, it might be interesting to consider in the general case of whether such an architectural feature is needed.
     
    A client had topics in which most of the content applied across a range of products. However, towards the end of each of these topics (i.e. before the next heading), there would be a detailed drawing and callout descriptions that were specific
    to just one of those products. Clearly, fig was the right element to use, with a nested image and a descriptive list or table. However, they needed a way to swap out the figs for the particular context, keeping the rest of the topic generic. Of the standard
    options:
     

    It wasn’t realistic to keep all the possible figures in the topic and use conditional filtering. Translation would have cost more; the authoring experience wouldn’t have been great;
    and there are issues with pre-product conditions on a large scale anyway. Conkeyref is the obvious “variable chunk” mechanism, but at the time, the client’s CMS made this quite hard to use. UI support was minimal. Also, some of the client team were only
    just coping with the idea of basic DITA mechanisms. Conkeyref seemed too sophisticated for them to use effectively. Conref push had the same limitations as conkeyref — inadequate support in the tool and a challenging abstraction mechanism for struggling writers to grasp.
     
    What we did in the end was something a little unorthodox. In fact, I have had a little pushback on it since a new team came in with DITA purity as a primary focus. So I’m quite reassured that Rob and Eliot have mentioned usages along similar
    lines. ?
     
    The clients’ CMS had a really nice UI for managing maps and topics. So we decided to manage the variable fig elements in dedicated topics. However, we didn’t need or want to display the title of those fig-only topics in output. It was the
    title element of the fig itself that should be displayed, and used for lists of figures, cross-references, etc. So we did what Rob described — used the topic title as a label for internal management purposes only, and suppressed it in output. We defined a
    new topic shell for this purpose so authors and stylesheets alike could be clear what the effect should be.
     
    This mechanism did the job, although given that the CMS now supports conkeyref much better, and the new authoring team are more comfortable with some of the more complex but standard ways of working in DITA, if I were to approach the same
    situation now I might just suggest conkeyref.
     
    Back to Eliot’s original post, I would like to hear a bit more about the usability problems of conref / conkeyref for the L&T questions. There are certain CMSs that encourage people to define conreffable elements in separate topics anyway,
    which I would have thought could work well for this case. Is it just the unwanted title elements that are the problem?
     
    Cheers,
    Joe
     



    Joe Pairman Mekon Tel: +44-7739-522002 Mobile: +44-7472-745-063? Skype: joepairman
     

    From: <dita@lists.oasis-open.org> on behalf of Amber Swope <amber@ditastrategies.com>
    Date: Thursday, November 30, 2017 at 17:05
    To: Rob Hanna <rob@precisioncontent.com>, David Hollis <dhollis@aandoconsultancy.ltd.uk>
    Cc: dita <dita@lists.oasis-open.org>
    Subject: RE: [dita] Managing "contextless elements" as for L&T Assessments and Objectives


     

    Thanks for the notes, Rob and David.
     
    Many companies need to manage questions a separate units, which means that the easiest way to assemble them in a deliverable is to have separate topics and then organize them with a map. This also allows you
    to apply different key value to different questions in the context of a map. The L&T SC has determined that storing the questions as separate units is a requirement we need to support.

     
    As for the title discussion, I have not yet seen question title used for a publishing context. One could argue that the question stem may be relevant as a label for the topic, but question stems may be more than
    one paragraph and may be very generic. The real issue is that most folks don’t have anything to use as a label for a given question. So, I have been considering this challenge from the perspective of how folks use the topics.

     
    One of the primary use cases is assembling a collection of questions for a test. Because it is very common to have the same stem for multiple questions, the current out-of-the-box support in most editors is to
    display the title for the topic reference. This means that if you leave the title blank in the question topic, then the map is a list of nameless topic references. You essentially have to use a view with the resolved topics to know what you’re building. In
    many cases the order of the references isn’t important, but you need to know that you haven’t included the same question multiple times. You may also need to apply key references to specific questions so it is imperative that you know which question is referenced.
     
    For example, for a driver training course, you may have 500 topics with “Who has the right of way in the following traffic pattern?” as the question stem. What would be the label or title for these topics? If
    I’m assembling a map to test the learner’s knowledge about the concept of right of way, I could have 50 of these question in a map. To associate the relevant learning objective to the topic, I need to know which questions apply to which learning objective.

     
    When I consider the role that a title plays in this scenario, the issue is about what is displayed in the map rather than what is stored in the topic. I can think of several options to help with the display of
    relevant metadata is helpful, but none of them address the question of what, if anything, should be stored as the title or label of a question.
     
    Eliot proposed three options in the original email. Although an option, I don’t support the idea to directly use elements in the map. I’d like to investigate the first two options and any others that folks can
    propose. If you have other options, please contribute your suggestions.
     
    Have a great day, Amber
     
     
     
     


    From:
    dita@lists.oasis-open.org [mailto: dita@lists.oasis-open.org ]
    On Behalf Of Rob Hanna
    Sent: Thursday, November 30, 2017 7:05 AM
    To: David Hollis
    Cc: dita
    Subject: RE: [dita] Managing "contextless elements" as for L&T Assessments and Objectives


     
    While there are admittedly topic types where the title is not required for publishing, I think that every topic needs a label for identification and management purposes. The title plays a dual role as content and metadata
    (label). Could the solution be as easy as specializing a label element from title from some topic types where this is the case? I think label could be a useful substitution for title in any instance where the title is not needed for publication but still required
    for identification, such as sections and figures.
     
    Cheers,
    Rob Hanna
     


    From: dita@lists.oasis-open.org [ mailto:dita@lists.oasis-open.org ]
    On Behalf Of David Hollis
    Sent: Thursday, November 30, 2017 6:40 AM
    Cc: dita < dita@lists.oasis-open.org >
    Subject: Re: [dita] Managing "contextless elements" as for L&T Assessments and Objectives


     
    Hi Amber, Eliot,

     


    Isn't the generic DITA topic already quite "contextless"?


     


    I thought that chunking was the way to use a topic without the title? I assume there is a title somewhere, just it is not required for the "contextless" topic. This seems like a parallel to Information mapping?


     


    I would be concerned if the proposed solution would be to put content in a map, and would suggest a wider discussion about what the role of a map and a topic should be, going forward. I appreciate that metadata in a map is already used
    for various purposes: reuse and subject schemes, for instance. But one of the potential solutions would seem to go further than that. I acknowledge Eliot's caveats about this potential solution.


     


    There might be a parallel with resource-only "container topics", or "warehouse topics" that simply provide content for reuse. The topic itself never appears in the final document.


     


    My two penn'orth.


     


    HTH,


    David


     

     



    Thanks for the summary, Eliot.

     

    Although a single question is a unit that can be understood in isolation and used in multiple contexts, it doesn't meet the definition of a topic in that it does not natural title. This means that they fall into the gray area that you are
    calling “contextless elements”. I can't think of a better way to describe it and thank you for your suggested terminology.

     

    Because assessment and learning objectives are fundamental to learning content, we are definitely going to address this issue on the L&T SC. However, we don't want to do this in isolation, so if you have grappled with content that meets
    the same criteria, please share your experience with the TC.

     

    Many thanks,


    Amber