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?
- From: john_hunt@us.ibm.com
- To: dita-learningspec@lists.oasis-open.org
- Date: Sat, 7 Jul 2007 12:13:31 -0400
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]