Stage 1 Proposal: "Titleless" Topics and Context-Independent Content

[Eliot Kimber <ekimber@contrext.com>]

"Titleless" Topics 

[NOTE: In this proposal I use the term "publication" to mean "the assemblage of content represented by a root map created primarily to then produce deliverables intended to be read by humans, as opposed to other possible uses for maps that are not publications in this sense.]

Requirement: 

The ability to use topics where the title of the topic is considered "uninteresting" and, as such, is not reflected in normal deliverables produced from the topic. While the title element is required, it may have either empty content or arbitrary or even generated content that serves more as a unique identifier for content management purposes than as a descriptive title one would expect to see in a table of contents or in narrative flow.

Here the word "titleless" is in quotes because the topics must still have title elements, but for the purposes of presentation the title is ignored, as though the topic did not have a title at all. It also recognizes that title elements with empty content are both allowed and sensible in this context.

An example of this is topics containing Learning and Training interactions (questions and answers), where the requirement is to combine large numbers of individual questions into test structures where each question is contained in a separate topic but where the desired presentation result is as though all the questions under a single parent title had been in the body of a single topic, avoiding the need to use content references within multiple topics to achieve the same presentation result.

This concept of "titleless" topic then allows elements that would otherwise only be reusable only via content reference from within topics to be used from maps using normal topicrefs.

Proposal:

To satisfy the requirement for "titleless" topics, define two new specializations:

Specialization 1: New topic type for "titleless" topics

Define a new topic type, specialized from topic/topic, that has the explicit semantic of:  The title of this topic is not interesting or useful in normal presentations and should, by default, be omitted. The content of any abstract, the short description, and the content of the body of the topic should be presented as though they had occurred within the body of a topic that contains any siblings of the "titleless" topic. This topic type does not allow nesting of topics. 

By "normal presentation" is meant deliverables generated from the map that uses the "titleless" topic, e.g., books, Web sites, etc. It establishes the default presentation expectation for topics of this type. 

Use case: Topics that contain individual Learning and Training assessments for the specific purpose of enabling the construction of tests through a combination of normal topics to establish the test hierarchy (and provide any required context, e.g., instructions, learning metadata, etc.) and topics that contain the test questions.

Specialization 2: New topicref type for treating any topic as "titleless"

Define a new topicref type, specialized from map/topicref, that has the explicit semantic of "treat the referenced topic as though it were a 'titleless' topic."

Use case: Produce the same result as one would get from using the "titleless" topic type but from any topic type.

Background:

In DITA there are two basic forms of use-by-reference: 

* The use of topics from maps via topicrefs
* Content reference, which allows non-topic elements to be used from any context where the re-used element is allowed.

Another fundamental aspect of DITA's design is that topics must have titles. Having a title is an essential distinguisher between topics and all other elements in the DITA vocabulary. Topics are the atomic unit of content for publications. Topics are also intended to be more-or-less standalone units of reusable information. When organized by maps or literally nested within other topics, topic titles, by definition, define a strict hierarchy of titles, i.e., the table of contents of the publication.

While topics are intended to be context-independent, meaning that as an atomic unit of content topics can be used and re-used in different places with little or no concern about the context in which they are used, elements within topics are usually highly context dependent, contributing to the local narrative flow of the topic's content or providing metadata to specific elements within the topic or to the topic itself. For example, one would not normally expect a given paragraph to be freely re-usable in any context.

However, the experience of the DITA Learning and Training community is that there is a class of non-topic elements that are inherently without context: interactions (questions and answers as defined in the learning domain) and objectives.

Interactions, in particular, have the characteristic that they are, for the most part, individually independent of any context within which they might be used. For example, it is common practice to create tests by randomly selecting a set of questions from a much larger pool of questions. Likewise, in this scenario where there is a large collection of reusable questions, each question will be classified with metadata about its subject area, specific learning objectives or standards to which it applies, and so on, in order to facilitate the accurate selection of questions for a specific use (e.g., 7th-grade algebra for the state of Texas).

At the same time, the typical interaction does not have a natural title. The prompt of a question is usually not distinguishing (e.g., "What is the sum of the following numbers:").

As defined in DITA 1.x, interactions are elements within topics, not topics themselves. (In DITA 1.2 interactions specialized from <fig>, in 1.3 they specialize from <div>). And in general, questions are not appropriately modeled as topics--they are, fundamentally, content elements that go within topics.

However, the reuse requirements for interactions make use directly from maps much more convenient than using interactions via content reference from within topics. For example, if you are creating a test of hundreds of questions organized into a hierarchy it would be much more natural and much easier to do that work using a map and topicrefs than using multiple topics with many content references. Using maps, out-of-the-box map editing and management tools will work well. Using content references, out-of-the-box editors do not generally support the ease of creation, organization, and modification that is required in this use case.

Thus many users of the DITA Learning and Learning2 domains quickly realized that they really wanted to be able to treat questions as though they were topics for the purposes of defining test structures but also realized that these questions did not have natural titles and, even if they were put into topics that had titles, for publication purposes they would not want the titles reflected in the final output. Several of us in the Learning and Training community independently defined "question topics" that allowed this use of questions from maps. 

That is, the use of interactions from maps requires a topic whose title and non-body content (abstract or short description) is not presented. Essentially, the desire is to have the topics containing questions treated as though the contents of these topics had been the body content of whatever topic or topic head is the parent of these "question topics".

A similar requirement exists for objectives, in that the same objective definition may apply to many learning objects or elements within learning objects (e.g., interactions that serve to assess achievement of the objective).

Like interactions, objectives do not have natural titles beyond the objective statement itself and the objective statement may not, by itself, be distinguishing. (For example, two states may have the same learning objective, with the same objective statement text, but different metadata reflecting the existence of these state-specific objectives in different systems of learning standards.)

It would be useful, for example, to be able to use relationship tables to associate objectives, as standalone objects, with other learning objects or with specific points in a map hierarchy in order to establish the learning-object-to-objective relationships, rather than literally including the objectives in the learning objects, either as literal elements or via content reference, which are the only options today.

But again, as a matter of presentation, if objectives were in topics related using normal map-level mechanisms, the desire would be for the titles of the objective-containing topics to not be presented, only the objectives themselves.

Thus there is a general requirement for a type of topic and/or a type of topicref that explicitly means "the title of the topic is not intended to be used in normal presentations". 

--
Eliot Kimber
http://contrext.com