This Wiki page is designed to collect comments on the second review of the DITA 1.2 specification, 21 September - 3 October 2009. This review is being conducted by members of the OASIS DITA Technical Committee.

Contents

  1. Learning and training elements: A to Z
    1. lcAge
    2. lcAnswerContent
    3. lcAnswerOption
    4. lcAnswerOptionGroup
    5. lcArea
    6. lcAssessment
    7. lcAsset
    8. lcAttitude
    9. lcAudience
    10. lcBackground
    11. lcChallenge
    12. lcCIN
    13. lcClassroom
    14. lcClient
    15. lcConstraints
    16. lcCorrectResponse
    17. lcDelivDate
    18. lcDelivery
    19. lcDownloadTime
    20. lcDuration
    21. lcEdLevel
    22. lcFeedback
    23. lcFeedbackCorrect
    24. lcFeedbackIncorrect
    25. lcFileSizeLimitations
    26. lcGapAnalysis
    27. lcGapItem
    28. lcGapItemDelta
    29. lcGeneralDescription
    30. lcGoals
    31. lcGraphics
    32. lcHandouts
    33. lcHotspot
    34. lcHotspotMap
    35. lcInstruction
    36. lcInstructornote
    37. lcInteractionBase
    38. lcInteraction
    39. lcIntervention
    40. lcInterventionItem
    41. lcIntro
    42. lcItem
    43. lcJtaItem
    44. lcKnowledge
    45. lcLearnStrat
    46. lcLMS
    47. lcLom
    48. lcMatching
    49. lcMatchingHeader
    50. lcMatchingItem
    51. lcMatchingPair
    52. lcMatchTable
    53. lcModDate
    54. lcMotivation
    55. lcMultipleSelect
    56. lcNeeds
    57. lcNeedsAnalysis
    58. lcNextSteps
    59. lcNoLMS
    60. UlcObjective
    61. lcObjectives
    62. lcObjectivesGroup
    63. lcObjectivesStem
    64. lcOJT
    65. lcOpenAnswer
    66. lcOpenQuestion
    67. lcOrganizational
    68. lcOrgConstraints
    69. lcPlanAudience
    70. lcPlanDescrip
    71. lcPlanObjective
    72. lcPlanPrereqs
    73. lcPlanResources
    74. lcPlanSubject
    75. lcPlanTitle
    76. lcPlayers
    77. lcPrereqs
    78. lcProcesses
    79. lcProject
    80. lcQuestion
    81. lcQuestionBase
    82. lcResolution
    83. lcResources
    84. lcReview
    85. lcSecurity
    86. lcSequence
    87. lcSequenceOption
    88. lcSequenceOptionGroup
    89. lcSequencing
    90. lcSingleSelect
    91. lcSkills
    92. lcSpecChars
    93. lcSummary
    94. lcTask
    95. lcTaskItem
    96. lcTechnical
    97. lcTime
    98. lcTrueFalse
    99. lcValues
    100. lcViewers
    101. lcW3C
    102. lcWorkEnv
    103. lcWorkEnvDescription
    104. learningAssessment
    105. learningAssessmentbody
    106. learningBase
    107. learningBasebody
    108. learningContent
    109. learningContentbody
    110. learningContentRef
    111. learningContentComponentRef
    112. learningGroup
    113. learningObject
    114. learningOverview
    115. learningOverviewbody
    116. learningOverviewRef
    117. learningPlan
    118. learningPlanbody
    119. learningPlanRef
    120. learningPostAssessmentRef
    121. learningPreAssessmentRef
    122. learningSummary
    123. learningSummarybody
    124. learningSummaryRef
    125. lomAggregationLevel
    126. lomContext
    127. lomCoverage
    128. lomDifficulty
    129. lomInstallationRemarks
    130. lomIntendedUserRole
    131. lomInteractivityLevel
    132. lomInteractivityType
    133. lomLearningResourceType
    134. lomOtherPlatformRequirements
    135. lomSemanticDensity
    136. lomStructure
    137. lomTechRequirement
    138. lomTypicalAgeRange
    139. lomTypicalLearningTime

Previous | Next | Home page for the second review

Important: Reviewers, be sure to preface comments with your name and the date, for example, [Eberlein, 18 September 2009]

Learning and training elements: A to Z

[Eberlein, 21 September 2009] I think that this section should only contain topics that are not in the other sections. Then you could have a "Learning and training elements, A to Z" topic that would contain cross references to the existing topics.

As this is currently implemented, there is too much duplication of topics.

[RDAnderson, November 4 2009] Updated, with the input of John Hunt. There are now two groups under an "other" heading for remaining elements; duplicates are removed. I created an A to Z topic that goes at the end, using the same format as the A to Z topics in the base and Technical Content sections.

lcAge

lcAnswerContent

lcAnswerOption

lcAnswerOptionGroup

lcArea

lcAssessment

lcAsset

lcAttitude

lcAudience

lcBackground

lcChallenge

lcCIN

lcClassroom

lcClient

lcConstraints

lcCorrectResponse

lcDelivDate

lcDelivery

lcDownloadTime

lcDuration

lcEdLevel

lcFeedback

lcFeedbackCorrect

lcFeedbackIncorrect

lcFileSizeLimitations

lcGapAnalysis

lcGapItem

lcGapItemDelta

lcGeneralDescription

lcGoals

lcGraphics

lcHandouts

lcHotspot

lcHotspotMap

lcInstruction

lcInstructornote

lcInteractionBase

[RDAnderson, November 11 2009] This element is missing contains/contained-by information.

[RDAnderson, December 8 2009] This is now corrected.

lcInteraction

lcIntervention

lcInterventionItem

lcIntro

lcItem

lcJtaItem

lcKnowledge

lcLearnStrat

lcLMS

lcLom

lcMatching

lcMatchingHeader

lcMatchingItem

lcMatchingPair

lcMatchTable

lcModDate

lcMotivation

lcMultipleSelect

lcNeeds

lcNeedsAnalysis

lcNextSteps

lcNoLMS

UlcObjective

lcObjectives

lcObjectivesGroup

lcObjectivesStem

lcOJT

lcOpenAnswer

lcOpenQuestion

lcOrganizational

lcOrgConstraints

lcPlanAudience

lcPlanDescrip

lcPlanObjective

lcPlanPrereqs

lcPlanResources

lcPlanSubject

lcPlanTitle

lcPlayers

lcPrereqs

lcProcesses

lcProject

lcQuestion

lcQuestionBase

lcResolution

lcResources

lcReview

lcSecurity

lcSequence

lcSequenceOption

lcSequenceOptionGroup

lcSequencing

[Su-Laine Yeo December 30 2009] Many of the issues I raised for <lcTime> below also apply here: The data model is hard to use and the the purposes of @name and @datatype are not clear.

[JHunt 31 Aug 2010] At this point, there is nothing more specific I can add.

lcSingleSelect

lcSkills

lcSpecChars

lcSummary

lcTask

lcTaskItem

lcTechnical

lcTime

[Su-Laine Yeo December 30 2009]. I have issues with the data model for this element, and I also find the description to be very unclear.

My issues with the data model are as follows:

- Usability for authors: The main purpose of this element is to communicate the number of hours and minutes an activity is supposed to take. Typing these numbers is a frequent task that we should make as easy and fast as possible. In all authoring tools that I am familiar with, it is significantly easier and faster for an author to add PCDATA to an element than to enter an attribute value. The data model in the current draft of the 1.2 spec also forces authors to remember that they have to enter the @value value in an hours:minutes format.

- It is problematic for an optional element to have a required attribute. It is very helpful if team leads or vendors can give authors a template consisting of elements that the authors can then fill in with content. But if you include elements in the template that are missing a required attribute value, the document will fail validation.

- Possible conflicts between the element contents and the @value attribute. If you have <lcTime name=lcTime value="01:30">This activity requires 3 hours</lcTime> then what is a processor supposed to report? 1.5 hours or 3 hours? Or both?

I recommend that we change the syntax so that instead of expressing 1.5 hours as <lcTime name=lcTime value="01:30"/>, it be expressed as <lcTime><hours>1</hours><minutes>30</minutes></lcTime>. Then we can provide authors with templates containing lcTime><hours></hours><minutes></minutes></lcTime>, and the template will pass validation.

My issues with the clarity of the description are as follows:

- Descriptions of the @name and @description attributes, i.e. "The name used to indicate this data" and "The datatype for this data" are 100% unhelpful. I want to know how these attributes should be populated or processed, and why they are required.

- The sentence, "TimeValue -- look up something appropriate in XML schema terms here." makes no sense to me. Is it a reminder for the writer of the spec to do more research?

[JHunt 31 Aug 2010] Yes, agreed. I will revise these descriptions to make them more generic. There is no specific datatype support for these time values. I will revise to reflect that more generic case. Thanks for the comments.

lcTrueFalse

lcValues

lcViewers

lcW3C

lcWorkEnv

lcWorkEnvDescription

learningAssessment

learningAssessmentbody

learningBase

learningBasebody

learningContent

learningContentbody

learningContentRef

learningContentComponentRef

learningGroup

learningObject

learningOverview

learningOverviewbody

learningOverviewRef

learningPlan

learningPlanbody

learningPlanRef

learningPostAssessmentRef

learningPreAssessmentRef

learningSummary

learningSummarybody

learningSummaryRef

lomAggregationLevel

lomContext

lomCoverage

lomDifficulty

lomInstallationRemarks

lomIntendedUserRole

lomInteractivityLevel

lomInteractivityType

lomLearningResourceType

lomOtherPlatformRequirements

lomSemanticDensity

lomStructure

lomTechRequirement

lomTypicalAgeRange

lomTypicalLearningTime

LTelementsAtoZ (last edited 2010-08-31 14:13:25 by john_hunt)