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.

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

[Eberlein, 21 September 2009] This topic needs a short description.

[bnevin, 29 September 2009]

I think each section (base, tech content, L&T) is a map plus topics. None of them have a short description at the top, though each linked topic does. Are you asking for a short description at the map level? If so, that should be done for each map at this level.

JHunt 12/9/09 - not clear which topic is missing a shortdesc.

Overview and assumptions

[bnevin, 29 September 2009]

This section currently says:

The introduction to this section of the spec should not exemplify the writing conventions of content typically created for learning and training? It should alert the reader that the rest of the spec does so. How about:

The short descriptions of the overview sections of the several main sections (base, tech content, L&T) should be somewhat similar. The base section has an introduction to DITA, rather than to the base section. The Technical Content section says:

That seems a little weird, since you're in the spec reading that section. It seems to me that the overview in each case should briefly state the motivation for this grouping of elements. These might be something like:

JH 12/9/09 - I revised the shortdesc for the Overview and assumptions topic as follows:

Problem

Objectives of the DITA Learning and Training specialization

[bnevin, 30 September 2009]

Should we used the undefined buzz-phrase "intent-based authoring" here? It does not seem the same as discussed in this dissertation. Using the phrase in a different sense, IBM's GML was considered "intent-based markup", but SGML and XML are not so described.

JH 12/9/09 - Good points. Revised as follows:

"Provide a general top-level design for authoring of education content with good learning architecture, following DITA principles and best practices. "

Sometimes we overstate the case for DITA. Objective 2 is an example. It lists best practices for any XML, not just for DITA, and not introduced with DITA.

JH 12/9/09 - These may re-state general principles, but I think it's important to include this since many people reading this part of the spec may find this information helpful. These are key motivations for DITA adoption, even if they're simply basic principles of XML. And in any case, not all XML implementations follow them.

Objective 3: "general delivery"? What is meant by the word "general" here, and why not just say "delivery"? Or "delivery as learning and training content in a variety of forms, including print ..." etc.

JH 12/9/09 - Restated as follows:

"Provide basic support for processing DITA content for delivery as learning and training in a variety of forms, including print and presentation delivery to support instructor-led training (ILT) and web delivery for distance learning. "

Objective 5: ... so learning content developers do not have to start from scratch.

==> ... so learning content developers do not have to start from scratch because with minimal adaptation they are able to reuse content previously developed for other purposes.

JH 12/9/09 - Revised this statement as follows:

"Build on existing DITA infrastructures as much as possible, so learning content developers do not have to start from scratch because with minimal adaptation they can use standard approaches for DITA content and reuse content previously developed for other purposes."

The note at the end of this topic applies also to developing online help systems.

A learning objects approach to learning and training content

[bnevin, 30 September 2009]

DITA topic types provide the meaning and intention to content contained in instructional and information objects, and as such, comprise the basic building blocks for learning objects.

==> DITA topic types are the basic building blocks for learning objects and specify the meaning and intention of content provided instructional and information objects

[JTH: 28 Sept 2009 Fix verb tense (s) and unfinished sentence]

1. Uses a Learning map domain to identifies the learning objectives and identifies the content needs with a ??

[JHunt 12/9/09 - revised as suggested]

Learning objects and specialized DITA learning and training topic types

[bnevin, 30 September 2009]

Move the figure. Place it immediately after the paragraph that introduces it, and before the details beginning with "In this approach, a learning object comprises ...".

[JHunt 12/9/09 - revised as suggested]

The DITA learniongOverview, learningSummary, and learningAssassessments ...

==> The DITA learningOverview, learningSummary, and learningAssessments ...

information objects, which provide the source learning content - the ...

==> information objects, which provide the source learning content. The ...

Put a period . after each item in the numbered list. (List items must be parallel in punctuation, even if they do not stand alone as independent sentences. Either all with periods, or none. They are not a peculiar formatting of one long sentence.)

[JHunt 12/9/09 - revised as suggested]

Learning content design, authoring, and delivery through DITA specialization

[bnevin, 30 September 2009]

Move the figure. Place it immediately after the paragraph that introduces it. Split that paragraph, making a new paragraph beginning with "In this approach, a learning object comprises ...". Place that new paragraph and the details that follow it after the figure.

Uses a Learning map domain to identifies the learning objectives and identifies the content needs with a

==> Uses a Learning map domain to identify the learning objectives, which in turn guide retrieval of topic for reuse that are relevant for the content needs. [?? Trying to fill in missing words here.]

[JHunt 12/9/09 - revised in places suggested]

Put a period . after each item in the numbered list. (List items must be parallel in punctuation, even if they do not stand alone as independent sentences. Either all with periods, or none. They are not a peculiar formatting of one long sentence.)

In the figure, item 4: "Organizes ... and manage ..." ==> "Organizes ... and manages ..."

[JHunt 12/9/09 - revised in places suggested]

Use Cases

[JTH: 28 September 2009: “…fast index[ing], search, …” change to indexing

By structuring content with DITA topics and maps as self-contained learning objects matched with appropriate DITA metadata, it is possible to enable fast index, search, and retrieval of learning content that meets specific learning goals and objectives.

[JHunt 12/9/09 - revised in places suggested]

[JTH: 28 September 2009: “… learning objectives, [no comma here] and pull together …” remove comma between two dependent clauses

“… and patterns, and leverages …” remove comma]

[JHunt 12/9/09 - revised in places suggested]

Summary of learning topic, map, and domain designs

[JTH: 28 SEPTEMBER 2009

“… learning content itself, and enables direct …” remove comma

“…learning content, and can be presented …” remove comma

[JHunt 12/9/09 - revised in places suggested]

Fitting it all together with DITA learning content: maps, metadata, and topics

[bnevin, 30 September 2009]

Having all three topic types linked by one line to the entire block of L&T items suggests that the latter are topic combinations aggregated in a map. (Although if you look closely, the line seems to point just to learningContent in the middle of the box.) This impression is reinforced by the note under metadata domain that says "for both topics and maps". Yet map and bookmap are linked only to learningMap domain. On the right side, all the items are individually linked together, including learningBase (outside the box), and yet the two domains to the right are linked to just the box. Altogether, this diagram seems confused and is confusing and less than fully informative.

[JHunt 12/9/09 - removing this figure due to these confusions]

Learning map domain

[bnevin, 30 September 2009]

In the intro para, say that topics are aggregated by a sequence of topic references in a map. Provide some basis (other than prior knowledge of DITA) for understanding the role of the topicref specializations described in this section.

Is a learning bookmap not a learning-specific DITA map type? Can you provide an example that better illustrates the point?

such as course-level, module-level, or lesson-level.

==> such as course-level, module-level, or lesson-level collections.

[The rule is, hyphenate a modifier (preceding that which it modifies; and this hyphen can be omitted when the compound is very familiar or completely unambiguous. If you omit the noun being modified here, they're not compound modifiers, nor are they really compound nouns, so don't hyphenate.]

or other higher-levels of hierarchy ==> or other higher levels of hierarchy

[Not a compound noun or compound modifier, so no hyphen.]

[JHunt 12/9/09 - revised in places suggested]

Learning interactions domain

lcSequencing Presents choices in a list that the learning must arrange in a correct ordered sequence.

==> ... that the learner must arrange ...

[JTH: 29 September 2009: Punctuation correction. Although “Interactions” were built to support the notion of assessment,//comma here// they have been created as a DITA domain //no comma// and made available in the lcInteractions element in learningAssessmentbody.

[JHunt 12/9/09 - revised in places suggested]

Samples: DITA learning content about "Why DITA for learning and training?"

Samples ==> Examples. A sample is a random excerpt with some statistical probability of being representative. An example is a canonical instance that is selected or created so as to typify or exemplify what's being talked about.

[JTH: 29 September 2009: Correct the third sentence here. “ … DITA specification that make it … include a modular and topic-based architecture that allows for specialization and standard processing, to name a few.?]

There are many aspects to the DITA specification that makes it suitable for structuring learning content. As an evolving specification, extending it to areas like the learning industry not only helps learning professionals but contributes to DITA's overall success. Some of the aspects of the DITA spec that make it appropriate for learning include modular based architecture, topic oriented, allows for customization and standard processing to name a few.

DITA's modular architecture supports efficient reuse of content at the word, phrase,//comma here// or topic level. DITA also offers "specialization," which allows you to develop new elements and content models that are based on core DITA elements and content models. [This, change to Specialization ]helps you to customize DITA to support particular types of content while continuing to take advantage of the base DITA tools and transformations. For learning content, [this, change to specialization] enables the creation of specific content structures that can ensure that the right learners get the right information at the right time.

DITA is a topic-based architecture. It allows you to order, reorder, //comma here// and nest topics to create any kind of information product. Since content is not all //delete “all” // tied together in a single "book" but rather captured in chunks, using modular, topic-based chunks in various circumstances is easy to accommodate.

Topics can be used in more than one deliverable at once, independently from other topics. The real advantage here,//comma here// however, is that even though content is being used in more than one instance, the content itself remains as [a single change to “independent” ]unit. Modification of that content [would only need to: change to “need only”] happen in one place to accommodate all the instances of the appearance of that content.

A virtue of DITA specialization is that new elements and topic types can be processed using DITA's standard processing. [That, change to “standard processing”] means even though you have created "specializations",//commas belong inside quotation marks in US English] you can still process the specialized content without any or much additional stylesheet work. Of course, you may need to create specialized processing, to support some specialized types of content used in learning and training, such as assessment interactions. [Provide, change to “Providing”] meaningful semantics at a word, topic, //comma here// or section level can help preserve the instructional value of content. Reuse in a learning context will depend heavily on the model’s ability to preserve this value regardless of mode [for, change to “of”] delivery. Using DITA's specialization capabilities, “you can preserve” new elements that describe what content means to a learner [will be preserved, delete passive voice] at a content level regardless of delivery vehicle.

Learning models and best practice[s] are an evolving science. Using DITA for learning allows for the model to extend itself to evolving circumstances and best practices. Following DITA guidelines will ensure content is never locked into a proprietary format and can always be repurposed and reprocessed.

[JHunt 12/9/09 - revised these sections in places suggested]

Problems with unstructured content

Overview: Problems with unstructured content

Problems with unstructured content

Quiz: Problems with unstructured content

Summary: Problems with unstructured content

The benefits of structured content for learning and training

Overview: Benefits of structured content

Benefits of structured content

Quiz: Benefits of structured content

Summary: Benefits of structured content

Why DITA for learning and training content?

Overview: Why DITA for learning and training content?

Why DITA for learning and training content?

[JTH: 29 September 2009: Correct the third sentence here. “ … DITA specification that make it … include a modular and topic-based architecture that allows for specialization and standard processing, to name a few.?

There are many aspects to the DITA specification that makes it suitable for structuring learning content. As an evolving specification, extending it to areas like the learning industry not only helps learning professionals but contributes to DITA's overall success. Some of the aspects of the DITA spec that make it appropriate for learning include modular based architecture, topic oriented, allows for customization and standard processing to name a few.

DITA's modular architecture supports efficient reuse of content at the word, phrase,//comma here// or topic level. DITA also offers "specialization," which allows you to develop new elements and content models that are based on core DITA elements and content models. [This, change to Specialization ]helps you to customize DITA to support particular types of content while continuing to take advantage of the base DITA tools and transformations. For learning content, [this, change to specialization] enables the creation of specific content structures that can ensure that the right learners get the right information at the right time.

DITA is a topic-based architecture. It allows you to order, reorder, //comma here// and nest topics to create any kind of information product. Since content is not all //delete “all” // tied together in a single "book" but rather captured in chunks, using modular, topic-based chunks in various circumstances is easy to accommodate.

Topics can be used in more than one deliverable at once, independently from other topics. The real advantage here,//comma here// however, is that even though content is being used in more than one instance, the content itself remains as [a single change to “independent” ]unit. Modification of that content [would only need to: change to “need only”] happen in one place to accommodate all the instances of the appearance of that content.

A virtue of DITA specialization is that new elements and topic types can be processed using DITA's standard processing. [That, change to “standard processing”] means even though you have created "specializations",//commas belong inside quotation marks in US English] you can still process the specialized content without any or much additional stylesheet work. Of course, you may need to create specialized processing, to support some specialized types of content used in learning and training, such as assessment interactions.

[Provide, change to “Providing”] meaningful semantics at a word, topic, //comma here// or section level can help preserve the instructional value of content. Reuse in a learning context will depend heavily on the model’s ability to preserve this value regardless of mode [for, change to “of”] delivery. Using DITA's specialization capabilities, “you can preserve” new elements that describe what content means to a learner [will be preserved, delete passive voice] at a content level regardless of delivery vehicle.

Learning models and best practice[s] are an evolving science. Using DITA for learning allows for the model to extend itself to evolving circumstances and best practices. Following DITA guidelines will ensure content is never locked into a proprietary format and can always be repurposed and reprocessed.

[JHunt 12/9/09 - revised in places suggested]

Quiz: Why DITA for learning and training content?

[JTH: 29 September 2009] Question 1 Select the three benefits typically associated with using DITA.//add an end stop here//

DITA for learning can provide meaningful semantics at a word, topic, //comma here// or section level can help preserve the instructional value of content.

[JHunt 12/9/09 - revised in places suggested]

Summary: Why DITA for learning and training content?

The DITA learning and training content specialization

Overview: The DITA learning and training content specialization

The DITA learning and training content specialization

Quiz: The DITA learning and training content specialization

Summary: The DITA learning and training content specialization

LTArchSpec (last edited 2009-12-10 20:46:43 by john_hunt)