Unsung heroes of DITA (premium)

For some content developers—especially those using DITA for the first time—any features of DITA that go beyond the basics can seem intimidating. But sometimes, a special feature of DITA might be exactly what an organization needs to solve one of its content problems and save money. Features like conref push, subject scheme, and the learning and training specialization could play a powerful role in your content strategy—and they’re not as difficult to use as you might think.

Conref push

Conref push has the power to:

• Push content into a topic. With conrefs, you can pull content into a topic by reference. However, with conref push, you can insert or “push” content from a source topic into another topic. That way, when you open your published topic, you can actually see the content from the source topic. You might use conref push to add a step to a task or replace an item in an unordered list.
• Push content into a map. Conref push isn’t limited to adding or replacing elements in a topic—you can also use it to insert content into a map. This might include adding or replacing a topicref, changing a navtitle, or updating the map metadata. Conref push would be especially useful for organizations that have maps updated by people in multiple departments.
• Facilitate ultimate reuse! If you have reusable content, you can store it in a source topic and use conref push to insert it into the relevant destination topics. With conref push, you can modify topics by adding or replacing elements in a way that the original author never conceived.

Conref push works by looking for IDs in your destination topic specifying where the pushed content should go:

<task id="contentstrategy">

<title>Developing and implementing a content strategy</title>

  <taskbody>

    <steps>

      <step id="establish-goals"><cmd>Establish implementation goals and metrics.</cmd></step>

    </steps>

  </taskbody>

</task>

Then, in your source topic, conref push uses the conaction attribute to replace an existing element:

<step conref="contentstrategy.dita#contentstrategy/establish-goals" conaction="pushreplace"><cmd>Define implementation goals and metrics.</cmd></step>

Conref push also allows you to push content before or after an existing element. If you use the conaction attribute with a value of pushbefore or pushafter, you must do so in conjuction with another conaction attribute with a value of mark to specify the location of the pushed content:

<step conaction="pushbefore"><cmd>Identify and interview stakeholders.</cmd></step>

<step conref="contentstrategy.dita#contentstrategy/establish-goals" conaction="mark"><cmd/></step>

<step conref="contentstrategy.dita#contentstrategy/establish-goals" conaction="mark"><cmd/></step>

<step conaction="pushafter"><cmd>Define roles and responsibilities.</cmd></step>

Once you’ve set up your IDs in your destination topics and your conaction attributes in your source topic, you’ll need to add the source topic to the other topics via a map to see conref push in action.

If you need to reuse content across multiple departments in your organization, conref push is the perfect hero for the job. Suppose you have two teams—tech comm and training—that share a lot of instructional content. The training team needs to use the instructions in the tech comm team’s topics, but they also need to add some information that is specific to the training department.

The tech comm team doesn’t want to be saddled with adding training-specific content to their topics (or setting up the conditions that would require). With conref push, the training team can add their own content to the topics instead—problem solved!

Subject scheme

Subject scheme has the power to:

• Define custom controlled values in a map. Much like a standard DITA map uses topicrefs to define a collection of topics, a subject scheme map uses key definitions to define a collection of controlled values. This means you can create a taxonomy of custom values without having to write a specialization. To use a subject scheme map, you must reference it in the highest-level DITA map that needs to use the controlled values within it.
• Manage relationships between controlled values. A subject scheme map sets up a hierarchy of controlled values and allows you to divide these values into categories. You can also bind the custom controlled values you create to metadata attributes.
• Build the framework for ultimate faceted search! A subject scheme map allows you to classify large amounts of information. The values you define can be used as facets to set up a controlled, sophisticated search of your content. To take advantage of this power, you’ll need content management and authoring tools that support faceted search.

A subject scheme map defines controlled values, or keywords that identify metadata attributes, using the subjectdef element. The highest-level subjectdef elements define categories of metadata, and their child subjectdef elements define the values. By adding further levels of child subjectdef elements, you can divide these values into sub-categories:

<subjectScheme>

  <subjectdef keys="vehicles">

    <subjectdef keys="car"/>

    <subjectdef keys="motorcycle"/>

    <subjectdef keys="boat">

      <subjectdef keys="racing"/>

      <subjectdef keys="fishing"/>

    </subjectdef>

  </subjectdef>

</subjectScheme>

Once you’ve defined your custom controlled values, you can use the enumerationdef element to bind them to metadata attributes:

<subjectScheme>

  <subjectdef keys="vehicles">

    ...

  </subjectdef>

<enumerationdef>

  <attributedef name="audience"/>

  <subjectdef keyref="vehicles"/>

</enumerationdef>

</subjectScheme>

With a subject scheme map, you don’t have to store attribute values in each content contributor’s DITA editor. As long as the DITA editor understands the subject scheme, the attribute values will be available to all who edit the maps or topics.

Your company might benefit from using a subject scheme map if you distribute a large number of products and need a better way to categorize them so that they are easier to find. For example, if your company sells engines, your customers should be able to search for the documentation on the engine they need according to criteria such as the relevant type of vehicle (car, motorcycle, boat), release version (1.0, 1.1, 2.0), and locations sold (United States, India, Japan).

By defining this information in a subject scheme, your customers will be able to find your content in a more targeted way than they can using a table of contents, an index, or full text search—the usual methods available with basic DITA.

Learning and training

The learning and training specialization has the power to:

• Structure a curriculum using specialized DITA. Just as standard DITA can be used to structure technical content in a manual with sections, the learning and training specialization can structure learning content in a course with lessons. Each lesson (or the whole course) can have a plan and an overview before it, and a summary and an assessment after it. Learning content topics can also contain standard concept, task, and reference topics.
• Create and manage tests and quizzes. The learning and training specialization includes the learning assessment topic type, which contains elements for different types of test questions. In a learning assessment topic, you can store a question, its answer, the number of points it’s worth, and some feedback for the user. This puts the test and the answer key in a single source, which makes it easier to update the assessment material.
• Develop amazing e-learning! With the learning and training specialization, you can instruct students over the web with interactive courses and grade their assessments automatically. (See learningDITA.com for an example!)

With the learning and training specialization, you can structure a course to follow this ideal framework:

<map>

  <learningPlan/>

  <learningOverview/>

  <learningContent>

    <concept/>

    <task/>

    <reference/>

  </learningContent>

  <learningSummary/>

  <learningAssessment/>

</map>

But what happens when you need learning content in both the virtual and the physical classroom? Because the learning and training specialization was designed for e-learning, it only provides types of assessment questions that could be answered electronically—such as true/false, matching, multiple choice, sequencing, and open-ended questions—by default.

However, the learning and training specialization can be further specialized and customized to suit your needs. For example, you could specialize the open question type to include blank lines for a student’s handwritten answer. You could also use specialization to create new question types intended for use in a physical classroom, such as filling in a blank or circling a word or phrase.

Assemble!

Conref push, subject scheme, and the learning and training specialization are all part of DITA 1.2, which means that they can be used together. You might…

• use conref push to keep your subject scheme map up-to-date,
• reuse content between lessons or tests with the help of conref push, or
• keep track of controlled values related to an e-learning course using a subject scheme.

You might even solve your content problems by using all three. Your strategy doesn’t have to be limited to just one of these features—if you have a strong business case for it, feel free to call in the whole team!

These unsung heroes of DITA may not have a place in the spotlight (yet), but the more they’re used, the more they’ll catch on. As DITA 1.3 becomes more established and more widely supported, the features introduced with DITA 1.3 will become the new unsung heroes, which will give features from DITA 1.2 such as conref push, subject scheme, and the learning and training specialization the chance to become leaders of a bigger and better team.

If you’re having issues with your content and you think these heroes could help, don’t be afraid to call them in—they’re not as intimidating as they look, and they just might be able to save the day!