OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

dita-learningspec message

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


Subject: DITA learning content - to nest or not to nest?



This is also posted to our learning SC wiki - http://wiki.oasis-open.org/dita/LearningContent/LearningContentTopicSamples.

All of the samples are available with the updated learningsc plugin posted with our OASIS DITA learning SC Documents - http://www.oasis-open.org/apps/org/workgroup/dita-learningspec/download.php/24552/learningsc_plugin.zip

--------------------------------------------------------------------------------
Hello all OASIS DITA learning content sub-committee members and observers -

Building from our discussion this week about the learning content topic type, I've put together several alternative samples with the Managing mail topic set we looked at during the meeting.

The key questions about learning content for me are the following:

  * Can we enable and support *direct* use of the DITA core topic-concept-task-reference topic types as learning content, without requiring learning-specific specializations of the DITA content types?
  * By extension, if we can support direct use of the core DITA content types, then we can support direct use of *any* desired DITA content type.
  * What, if any, learning-specific content is essential to provide with DITA content types, to integrate them into a learning context?
     Our current design for learningContent includes section-level specializations for  lcIntro (optional), lcDuration (optional), lcChallenge (optional), and lcInstruction (optional).
  * How can we provide a "starter set" for learning content and make it as easy as possible to author, manage, process, and deliver DITA content as learning?

Please review the samples below, consider my comments about advantages and disadvantages, and respond back to this list with your comments. Let's plan to discuss in detail at our regular meeting next Thursday, July 12 at the new 4-5 PM EDT time.

Come prepared next Thursday to reach agreement on how which of these design options to use.

Thanks.

John
___________________________________
John Hunt
Lotus Education Development
Chair, OASIS DITA learning and training content sub-committee
IBM Software Group/Lotus Software
john_hunt@us.ibm.com


------------------------------------------------------------------
The samples
------------------------------------------------------------------

All of the samples are available with the updated learningsc plugin posted in our SC Documents - xxxxx.

Unzip the plugin to the demo folder in the DITA OT root folder (for example, c:\DITA-OT1.3.1), and sample htmlhelp output are available in demo\learningsc\mail_topics\out. More info about this is in the mail_sample_readme.

The plugin zip includes htmlhelp results for 4 sample sets of content.

------------------------------------------------------------------
1) Sample 1 - learning_mail_map1.chm
------------------------------------------------------------------
The first sample makes no use of learningContent topics at all, but uses the following learning map to describe a learningObject and topicrefs directly to DITA concept and task topics, with a learningOverview and learningSummary as bookend topics.
------------------------------------------------------------------
<!-- All core task-concept-reference content topics with topicrefs -->
<!-- Objectives in the learningOverview -->
<!-- No learningContent topics used at all -->
<learningObject href=""understanding_mail_basics_top.dita"" collection-type="sequence" type="learningOverview">
  <learningOverviewRef href=""understanding_mail_basics_overview.dita"" type="learningOverview"/>
  <topicref navtitle="Your Mail Inbox" id="mail_inbox" href=""mail_c_inbox.dita"" type="concept"/>
  <topicref navtitle="Displaying the inbox" id="display_inbox" href=""mail_Displaying_the_inbox.dita"" type="task"/>
  <topicref navtitle="Opening a message" id="open_message" href=""mail_Opening_a_message.dita"" type="task"/>
  <topicref navtitle="Moving messages to folder" id="move_messages" href=""mail_Moving_messages_to_a_folder.dita"" type="task"/>
  <learningSummaryRef href=""understanding_mail_basics_summary.dita"" type="learningSummary"/>
</learningObject>
------------------------------------------------------------------
Advantages of this approach:
 * Simple, direct use of existing DITA content.
 * No additional assumptions for creating learning content.
 * Can package any content as learning by providing learningOverview, learningSummary, learningAssessment topics in a learningObject map.

Disadvantages:
 * Cannot associate specific objectives with specific learning content.
 * Cannot add other learning-specific information to the learning content topics.

------------------------------------------------------------------
2) Sample 2 - learning_mail_map2.chm
------------------------------------------------------------------
[This is follows the current design for learningContent; see http://wiki.oasis-open.org/dita/LearningContent/LearningContentTopicType.]

This sample puts the learning content into learningContent topics, with learning-specific section specializations in the learningContent topic and the actual content as nested DITA concept and task topics in the learningContent topic.

The map uses learningContentRef to include the learningContent topics.
------------------------------------------------------------------
<learningObject href=""understanding_mail_basics_top.dita"" collection-type="sequence" type="learningOverview">
  <learningOverviewRef href=""understanding_mail_basics_overview.dita"" type="learningOverview"/>
  <learningContentRef href=""learningContent_mail_c_inbox.dita.dita"" type="learningContent"/>
  <learningContentRef href=""learningContent_mail_inbox_and_open.dita"" type="learningContent"/>
  <learningContentRef href=""learningContent_mail_Moving_messages.dita.dita"" type="learningContent"/>
  <learningSummaryRef href=""understanding_mail_basics_summary.dita"" type="learningSummary"/>
</learningObject>
------------------------------------------------------------------

Here's a sample topic, with lcDuration and lcObjectives in the learningContentBody, and the nested "Your mail inbox" concept topic.
------------------------------------------------------------------
<learningContent id="learningcontent">
        <title>Your Mail Inbox</title>
        <learningContentbody>
                <lcDuration>
                        <title>Duration</title>
                        <lcTime value="00:02">2 minutes</lcTime>
                </lcDuration>
                <lcObjectives>
                        <lcObjectivesStem>When you complete this topic, you'll know how the following
                                about mail basics:</lcObjectivesStem>
                        <lcObjectivesList>
                                <lcObjective>The purpose of the mail inbox</lcObjective>
                        </lcObjectivesList>
                </lcObjectives><?Pub Caret?>
        </learningContentbody>
       
        <concept id="mail_inbox_concept" xml:lang="en-us">
                <title>Your Mail Inbox</title>
                <shortdesc>Use your mail inbox to track and manage incoming messages.</shortdesc>
                <conbody>
                        <p>Knowing which messages you have not yet read and which ones are urgent
                                can help you decide how to best review a long list of messages. Unread messages
                                are indicated by bold text and a variety of icons identifies a characteristic
                                of the message, such as a high priority message or an invitation.</p>
                </conbody>
        </concept>

</learningContent>
------------------------------------------------------------------

Advantages of the Sample 2 approach:
 * Each learningContent topic includes the specific objective for that specific content.
 * The learningContent topics may include additional learning-specific information about the content, namely, lcIntro (optional), lcDuration (optional), lcChallenge (optional), and lcInstruction (optional).
 * The learningContent topic can incorporate existing DITA content by specifying the location with a conref.
 * The learningContent topic can also include an optional nested-topic content for learningAssessment or learningSummary.

Disadvantages of the Sample 2 approach
 * Titles may get repeated, especially if there is a single learningContent topic for a single nested task-concept-reference topic.
 * However, the title of the nested topic can be kept out of the processed result by specializing the output transform, which is what I've done for the results you see in learning_mail_map2.chm.

------------------------------------------------------------------
3) Sample 3 - learning_mail_map3.chm
------------------------------------------------------------------
Sample 3 avoids nesting DITA concept-task-reference topics in learningContent, but uses learningContent topics to provide objectives and other learning-specific information about the content in the concept-task-reference topics.

It does this by providing a learningContent topic for each concept-task-reference topic, and pairing them with topic references in the learning map, as shown below.

------------------------------------------------------------------
<learningObject href=""understanding_mail_basics_top.dita"" collection-type="sequence" type="learningOverview">
  <learningOverviewRef href=""understanding_mail_basics_overview.dita"" type="learningOverview"/>
  <learningContentRef href=""learningContent_lcObj_mail_c_inbox.dita.dita"" type="learningContent"/>
    <topicref navtitle="Your Mail Inbox" id="mail_inbox" href=""mail_c_inbox.dita"" type="concept"/>
  <learningContentRef href=""learningContent_lcObj_mail_Displaying_the_inbox.dita"" type="learningContent"/>
    <topicref navtitle="Displaying the inbox" id="display_inbox" href=""mail_Displaying_the_inbox.dita"" type="task"/>
  <learningContentRef href=""learningContent_lcObj_mail_Opening_a_message.dita"" type="learningContent"/>
    <topicref navtitle="Opening a message" id="open_message" href=""mail_Opening_a_message.dita"" type="task"/>
  <learningContentRef href=""learningContent_lcObj_mail_Moving_messages_to_a_folder.dita"" type="learningContent"/>
    <topicref navtitle="Moving messages to folder" id="move_messages" href=""mail_Moving_messages_to_a_folder.dita"" type="task"/>
  <learningSummaryRef href=""understanding_mail_basics_summary.dita"" type="learningSummary"/>
</learningObject>
------------------------------------------------------------------

Sample topic content consists of two separate DITA topic files.
  * learningContent_lcObj_mail_c_inbox.dita.dita provides lcIntro and lcObjectives in a learningContent topic.
  * mail_c_inbox.dita provides the concept topic about the mail inbox.

These are the same topics used in Sample 2, except here they're kept in separate DITA files.

------------------------------------------------------------------
<!-- lcObj_mail_c_inbox.dita learningContent topic -->
<learningContent id="learningcontent">
        <title>Your Mail Inbox - learningContent<?Pub Caret?></title>
        <shortdesc>(learningContent; no nested content)</shortdesc>
        <learningContentbody>
                <lcDuration>
                        <title>Duration</title>
                        <lcTime value="00:02">2 minutes</lcTime>
                </lcDuration>
                <lcObjectives>
                        <lcObjectivesStem>When you complete this topic, you'll know how the following
                                about mail basics:</lcObjectivesStem>
                        <lcObjectivesList>
                                <lcObjective>The purpose of the mail inbox</lcObjective>
                        </lcObjectivesList>
                </lcObjectives>
        </learningContentbody>
</learningContent>
------------------------------------------------------------------

------------------------------------------------------------------
<!-- mail_c_inbox.dita concept topic -->
<concept id="mail_inbox_concept" xml:lang="en-us">
        <title>Your Mail Inbox</title>
        <shortdesc>Use your mail inbox to track and manage incoming messages.</shortdesc>
        <conbody>
                <p>Knowing which messages you have not yet read and which ones are urgent
                        can help you decide how to best review a long list of messages. Unread messages
                        are indicated by bold text and a variety of icons identifies a characteristic
                        of the message, such as a high priority message or an invitation.</p>
        </conbody>
</concept>
------------------------------------------------------------------

The resulting output has one topic with the learning specifics for the content, such as duration and objectives, followed by the content topic.

Advantages of the Sample 3 approach
 * Keeps the learningContent separate from the core content.

Disadvantages of the Sample 3 approach
 * Keeps the learningContent separate from the core content, making it difficult for authoring and delivery.

------------------------------------------------------------------
4) Sample 4 - learning_mail_map4.chm
------------------------------------------------------------------
You might call this final sample the "all-in-one" content sample.

A single learningContent topics nests the four DITA concept-task content topics, and provides an aggregate objectives list, duration, and other learning-specific information.

This results in a simple map shown below, with an overview reference, content reference, and summary.

------------------------------------------------------------------
<learningObject href=""understanding_mail_basics_top.dita"" collection-type="sequence" type="learningOverview">
  <learningOverviewRef href=""understanding_mail_basics_overview.dita"" type="learningOverview"/>
  <learningContentRef href=""learningContent_allinone.dita.dita"" type="learningContent"/>
  <learningSummaryRef href=""understanding_mail_basics_summary.dita"" type="learningSummary"/>
</learningObject>
------------------------------------------------------------------

Here's what the all-in-one learningContent topic looks like, with lcDuration and lcObjectives and four nested concept and task topics in a single learningContent topic.
------------------------------------------------------------------
<!-- learningContent_allinone.dita.dita learningContent topic -->

<learningContent id="learningcontent">
        <title>Mail Basics<?Pub Caret?></title>
        <learningContentbody>
                <lcDuration>
                        <title>Duration</title>
                        <lcTime value="00:18">18 minutes</lcTime>
                </lcDuration>
                <lcObjectives>
                        <lcObjectivesStem>When you complete this lesson, you'll know how to perform
                                the following mail basics:</lcObjectivesStem>
                        <lcObjectivesList>
                                <lcObjective>Viewing the inbox</lcObjective>
                                <lcObjective>Opening a message</lcObjective>
                                <lcObjective>Moving messages to a folder</lcObjective>
                        </lcObjectivesList>
                </lcObjectives>
        </learningContentbody>
        <concept id="mail_inbox_concept" xml:lang="en-us">
                <title>Your Mail Inbox</title>
                <shortdesc>Use your mail inbox to track and manage incoming messages.</shortdesc>
                <conbody>
                        <p>Knowing which messages you have not yet read and which ones are urgent
                                can help you decide how to best review a long list of messages. Unread messages
                                are indicated by bold text and a variety of icons identifies a characteristic
                                of the message, such as a high priority message or an invitation.</p>
                </conbody>
        </concept>
        <task id="mail_1" xml:lang="en-us">
                <title>Displaying the inbox</title>
                <shortdesc>The Inbox view shows a list of messages you've received.</shortdesc>
                <taskbody>
                        <steps>
                                <step>
                                        <cmd>Click the Mail icon in the Bookmark bar.</cmd>
                                        <info><p><image href=""images\icons\mail_icon.gif"" alt="Mail icon"></image></p></info>
                                </step>
                        </steps>
                </taskbody>
        </task>
        <task id="mail_2" xml:lang="en-us">
                <title>Opening a message</title>
                <shortdesc>Whenever new mail is found you will see the <msgph>You have new
                                mail</msgph> status message.</shortdesc>
                <taskbody>
                        <steps>
                                <step>
                                        <cmd>You can display a message in the preview pane or open a message on a
                                                tabbed page. </cmd>
                                        <choices>
                                                <choice>To display a message in the preview pane, click the subject of a message.
                                                        If necessary, click <menucascade><uicontrol>View</uicontrol><uicontrol>Show</uicontrol>
                                                        <uicontrol>Preview</uicontrol></menucascade> and then click <uicontrol>Expand</uicontrol> or
                                                        <uicontrol>Collapse</uicontrol> to expand or collapse the preview pane. </choice>
                                                <choice>To open a message and display it on a tabbed page, double-click the
                                                        message.</choice>
                                        </choices>
                                        <info><note>The preview pane displays only one message at a time. To open
                                                        and view multiple messages, open the messages on tabbed pages.</note></info>
                                </step>
                        </steps>
                </taskbody>
        </task>
        <task id="mail_3.1" xml:lang="en-us">
                <title>Moving messages to a folder</title>
                <shortdesc>To store a message in a different folder, move the message.</shortdesc>
                <taskbody>
                        <steps>
                                <step>
                                        <cmd>In the message list, select one or more messages to move.</cmd>
                                </step>
                                <step>
                                        <cmd>Above the message list, click the arrow beside Folder, and then click
                                                Move to Folder.</cmd>
                                </step>
                                <step>
                                        <cmd>Select a folder.</cmd>
                                </step>
                                <step>
                                        <cmd>Click OK.</cmd>
                                </step>
                        </steps>
                </taskbody>
        </task>
</learningContent>
------------------------------------------------------------------

Advantages of the Sample 4 approach
 * Collects closely-related learning content into a single DITA topic.
 * In this case, the processing issue with title repeats is not as problematic, since each of the content topics has its own title.
 * Could have several sets of learning content like this in a single learning object collection.

Disadvantages of the Sample 4 approach
 * Cannot easily associate objectives with specific content.
 * Cannot easily disaggregate the content for different sequencing, and so forth.

------------------------------------------------------------------
5) Sample 5 - Not implemented in this set
------------------------------------------------------------------
A fifth option is to go the route of developing learning-specific specializations for the DITA content types, starting with the core topic, concept, task, and reference types. This is the route that we saw in Robin's PTC demo.

So, we would specialize DITA task as lcTask, for example, and add to lcTask the section-level specializations for  lcIntro (optional), lcObjectives (optional) , lcDuration (optional), lcChallenge (optional), and lcInstruction (optional) that we have in learningContent.

Advantages of a Sample 5 approach
 * You get to create a task with learning-specific information.

Disadvantages of a Sample 5 approach
(and I see these as show-stoppers)
 * You can't directly use existing DITA content topics, without specializing them for learning-specific content.
 * So, if I have 2000 existing task-concept-reference topics about Aircraft XYZ engine maintenance, I can't use them as is - I need to re-do that content within the context of lcTask, lcConcept, and lcReference topics.


------------------------------------------------------------------
Bottom line: If the double <title> is the only issue getting in the way of using learningContent, then that's an easy one to overcome by relatively simple processing specialization.

And we will need to do processing specialization for learning content, anyway.


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