Re: [dita-learningspec] dita learning spec cleanup review and comments

[john_hunt@us.ibm.com]

Wayne,

First, thanks very much for your very
helpful and detailed spec review.

Here's my comments on your comments.

1) On your recommendation to "Use
the word “GROUP” in container element names that wrap lists and options.
This will align with three renamed elements in S1000D. "

lcObjectivesList would become lcObjectiveGroup

lcQuestionOptions becomes lcQuestionOptionGroup
lcSequenceOptions becomes lcSequenceOptionGroup

JH: I have no objections. Any other
thoughts from SC members?

2) Comment: (In the PDF) provide more
labeling for the sections. 
JH: Agree it would be nice in the PDF.
Will try to accomodate.

3) "<lcAudience>, <lcResources>
and <lcDuration> are first mentioned in the <learningOverviewbody>
content model on page 100. They are not defined until the <learningBasebody>
on page 111. Insert a reference, such as “See blah blah for a definition.”

JH: When viewed in Adobe Reader, you
do get live links to these sections. However, will add a cross-reference
for print-only convenience.

4) learningBase and how to treat it
in the spec.

JH: learningBase is defined as a specialized
topic type, to provide a set of base elements for use in the more specialized
learning topic types.

That said, I see these alternatives
for the content, in the PDF version:

a) repeat the content about lcIntro,
lcNextSteps, etc, in each topic where they get used. Advantage: content
is right where you need it. Disadvantage: Content gets repeated and bloats
the size of the PDF/print.
b) include the learningBase topic and
the base elements, and include a print-only reference to the learningBase
elements as needed.

Again, with the html and "live"
PDF in Adobe Reader, all of these references become links, so I think most
of the problem goes away in those cases.

5) Where do you find references to learningOverviewInfoTypes
and learningContentInfoTypes ?

6) on repeating intro, duration, objectives,
I take it you mean on repeating the doc for them, or do you mean repeating
the elements themselves?

See comments on #4.

7 & 8) on lcChallenge and lcInstruction
in learningContentbody.

JH: I ask the group to consider if we
need this in the learningContent topic or not. If we do, then I'd like
to hear from Reuben on the proper order.

9) in the learningContent topic, <task>,
<concept>, and <reference> are available as "nested"
topics. A nested topic is not part of the body content of a topic, but
an entire, fully-valid DITA topic that is nested, either directly or by
conref, in a specific location. 

This DITA model derives from generic
topic, like this:

<!ELEMENT topic (%title;, (%titlealts;)?,
(%shortdesc;)?, 
           
    (%prolog;)?, (%body;)?, (%related-links;)?,
           
    (%topic-info-types;)* ) 
>

Here, the %topic-info-types; is what
defines additional info types (topic types) that you can include as nested
sub-topics in a DITA topic.

Specifically, in the learningContent
design, we define learningContent-info-types as follows:

<!ENTITY % learningContent-info-types
"(concept | task | reference | topic)*, (learningAssessment)?, (learningSummary)?">

See http://wiki.oasis-open.org/dita/LearningContent/Structure/DITASpecialization.

10) on duplicating lcObjectives in overview
and content bodies, yes, this is intentional. lcObjectives is also in the
summary body. And based on our recent discussions, I would propose that
we also make it available in the assessment topic.

Doing this makes it possible to a) use
the same objectives across the topics, b) include objectives from one topic
into another by way of conref (so, you could author the objectives in the
content topics, and conref them into the overview and summary, for example),
c) by output processing, to collect objectives from content topics and
populate the overview and summary topic, or the like.

11) on description of lcNextSteps -
do you have an alternative to suggest?

12) yes, we need a /SingleSelect close
tag on page 108. Good catch!

13) lcCorrectResponse is defined in
the DTD/XSD as an empty element. So, the markup examples are wrong, and
should be corrected. Good catch #2!

14) Comments well take on the assessment
topic markup examples. And, removing them "fixes" the problems
just mentioned in 12 and 13, too.

15) Defining the interactions as a domain
makes them available for use in other topic types, in addition to the assessment
type. And the assessment type does include lcInteractions, which references
the 6 interactions. How about I add a better description and cross-reference
for them?

16) Good comments.

17) QuestionOption vs. AnswerOption,
etc. Yes, I see what you mean. Let's decide whether to change, based on
group input.

18) on lcAsset - it actually provides
for just <image>, <imagemap>, and <object>. 
Now that you ask, since these are all
part of the content model for <p>, then could all be included directly
in the lcQuestion. 

So my question for the group is - do
we need lcAsset? What purpose does it provide?

19) on lcCorrectResponse - actually,
I'd say the opposite. Since only one element in a true/false, single select,
or multiple select might be correct, then lcCorrectResponse must be optional
for all the question options - it only gets included for the correct option(s).

20) DITA topics have a consistent structure,
and include a body element.

See http://docs.oasis-open.org/dita/v1.1/CD01/archspec/dita_spec_22_topics_structure.html.

21) I'll make the change for your affiliation.

22) Yes, agree these are not questions
- will remove the ?'s.

23) Yes, agree to reword to take out
the 'we'- thanks!

24) These objectives are the agreed-upon
and published objectives for this sub-committee, so would not want to change
these statements unless we change the objectives, as stated here - http://www.oasis-open.org/apps/org/workgroup/dita-learningspec/.

25) Yup, page 8 is blank.

26) Let's discuss your comments on the
examples in chapter 8. I'm open to what is best to do here.

I'll pull out items from this that we
need to discuss further at the Thursday meeting.

Thanks much much again, Wayne.

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