[This blog post was originally published on the IXIASOFT website on June 11, 2015 as “What Can We Expect with DITA 1.3?“. It is reproduced here with permission].
The top-of-mind question for nearly everybody at this year’s CMS/DITA North America conference was: “What can we expect with DITA 1.3?”
2015 marks the 10th anniversary of the original DITA specification launch, and five years since the release of DITA 1.2. From the start, DITA was designed around the idea of content reuse, but DITA 1.2 brought in a slew of further innovations, including the idea of indirect addressing based on map-defined keys, constraints, using subjectScheme for defining controlled vocabularies, plus the Learning & Training specialization among others. DITA 1.2 was a sea-change in how people thought and worked with their structured content, so it is only natural for people to wonder what DITA 1.3 will bring.
A casual glance at the speaker line-up for DITA NA 2015 revealed the names of those who are the main drivers behind the upcoming specification, so if you were hoping to learn more about DITA 1.3 at the conference, you definitely went to the right place.
Enhancements and Changes in DITA 1.3
One of the first talks of the second day of the conference was a well-attended presentation by JoAnn Hackos (organizer of the conference and chair of the OASIS DITA Adoption committee) and Kristen Eberlein (chair of the OASIS DITA Technical Committee) called simply: “What’s Coming in DITA 1.3”. They divided their talk into two main areas: things about DITA 1.3 that Content Creators would want to know and those areas of the specification aimed more at Information Architects. The section aimed at Content Creators focused on the mechanics of the new tags being introduced, while the section for Information Architects looked more at expected improvements the specification will bring in terms of processing information. Both JoAnn and Kristen traded back and forth on their talk, expanding upon the material in their shared slidedeck, with the audience taking lots of notes. Between the two of them they covered all of the major enhancements to expect in DITA 1.3.
DITA 1.3 for Content Creators
The section devoted to content creators concentrated on the mechanics of the specification, mainly focusing on new tags, attributes and the new troubleshooting topic type.
With the new troubleshooting topic type content creators identify an issue, describe a possible cause or causes, concluding with instructions to remedy the problem. Troubleshooting has also been added to steps within task topics, and a new troubleshooting attribute for the note tag has been added. Content-Sensitive Help (CSH) has also been added, allowing content creators to set the attributes for a specific callback ID and its context.
A number of enhancements are coming to tables, including the ability to specify a rotation value for the table or individual cells, as well as accessibility enhancements. Those wanting to use SVG and MathML in their DITA will be able to do so natively, as they are “baked into” DITA 1.3. The new “XML mention” group of elements will allow content creators to reference elements, attributes, namespaces and more without having to resort to using entities for angle brackets anymore. The release management groups of tags are designed to assist in the production of automated release notes, based on comments authors add to topics describing significant features or updates to a product at the topic level. There are two new highlighting elements: the self-descriptive line-through and overline elements, a couple of additions to the Learning & Training specialization designed for more flexible multiple-question and multiple-answer content possible, and a new sort-as element designed to phonetically sort non-Western content (such as Japanese words) in an index or glossary.
Print is being replaced by the more versatile deliveryTarget attribute, allowing for any conceivable output type or device to be targeted, so long as you have the XSL transforms to do it. There are also a number of small, miscellaneous fixes, such as:
- allowing citations in titles
- draft-comment can be used in more places
- the text element can now be used just about anywhere making it a viable alternative for ph (phrase) for reuse purposes
…and more.
DITA 1.3 for Information Architects
The last half of JoAnn and Kristen’s presentation looked at the new ways DITA 1.3 content can be structured. The advent of scoped keys will make it possible for a given key to have more than one value for a map. There will also be the ability to have cross-deliverable addressing and linking, and the new ditavalref element provides the means to set unique conditions to topicrefs within a map, allowing for branched publications. The new specification is written using the RelaxNG standard, from which DTD and Schema versions will ultimately be derived from. RelaxNG a more flexible standard, making it easier to author things like document-type shells, plus specializations and constraints.
The new cascade attribute will enable architects to change the default cascading behavior for filtering attributes in maps, and the role for the div element has been expanded, so content creators can now use it for grouping blocks of material for reuse, and as a base for specialization for Information Architects.
Not surprisingly there were many questions for JoAnn and Kristen at the end of their presentation. One question that I distinctly remember was from an audience member asking why there was no talk of using variables instead of keys, with another audience member responding that variables are a proprietary mechanism used by a specific CMS to get around using keys, which are standards-compliant. Questions like this make it clear that some documentation teams have yet to fully migrate to DITA 1.2, so it will be interesting to see what changes DITA 1.3 will bring.
No Trouble with Troubleshooting
Many people stuck around in the same conference room for the subsequent presentation by Bob Thomas (Owner of Tagsmiths and a member of the DITA Technical Committee) on DITA 1.3 troubleshooting. Bob gave a tour of the new troubleshooting-related features coming in the new specification, talking both about its mechanics and the rationale for introducing yet another new topic type.
The Fifth Topic Type
Bob started out by explaining that he has been part of the technical writing community for a long time: 16 years as a content contributor at Bell and then 19 years as an Information Architect and Tools Specialist working at his own firm Tagsmiths. He talked about the long-standing need for providing troubleshooting documentation for users – something that pre-dates even his amount of time in the industry. But DITA has task and reference topics, so why bother with a new topic type for troubleshooting—which becomes the fifth topic type, following the original trio of concept, task, reference, plus the glossary topic type added in DITA 1.2. Bob’s reply to that question was that the new troubleshooting topic is designed to do the following:
- Provide better organization for content based on the well-known troubleshooting pattern, instead of trying to shoe-horn it into another topic type
- Allow writers to focus on addressing and solving specific problems users may encounter
- Provide the opportunity to label troubleshooting content, making it easier for users to find
Troubleshooting Mechanics
Bob then talked about the mechanics of the new topic type. The main structural elements (excluding elements common to other topic types) of the new troubleshooting topic type consist of the following new elements:
- Condition – describing a symptom that a user may encounter
- troubleSolution – one or more troubleSolutions, describing a possible resolution to the issue
- Cause – an optional follow-up for condition or troubleSolution describing a possible reason for the problem
- Remedy – an optional, step-wise description of how to fix the problem, which can also include the optional responsibleParty element indicating who is expected to follow the remedy’s steps.
Bob also discussed the additional troubleshooting elements added to the task topic, and the trouble attribute added to the note element.
In the end, Bob made a convincing case as to why these new troubleshooting features were needed in DITA and that this will be a valuable additional tool for content creators to have.
Scoping Keys with Leigh W. White
IXIASOFT DITA Specialist, Leigh W. White ended this technical track with a presentation about DITA 1.3 key scopes. I was initially planning to take an early flight home until I saw the conference agenda and decided to push my flight back as I really wanted to see Leigh talk about this subject. I think that it is fair to say that everyone who attended her presentation did not leave disappointed, myself included.
Leigh started off by saying that she had spent a lot of time trying to understand the often convoluted and complex text of the draft DITA 1.3 specification on this subject, and that what was to follow was her best guess as to how things were supposed to work. With that caveat in mind she proceeded to talk about how standard, unscoped DITA 1.2 keys work, giving the following example:
<map>
<keydef keys="ot‐version">
<topicmeta>
<keywords>
<keyword>1.8</keyword>
</keywords>
</topicmeta>
</keydef>
<topicref href="introduction.xml"/>
</map>
So that when the keyword is referenced—using code like:
<ph keyref="ot-version"/>
…somewhere else in the same map—it will be resolved as “1.8”. Easy and straightforward. But problems arose when you had two or more keywords being defined, as the following examples demonstrate:
<map>
<title>Using the Widget</title>
<keydef keys="module‐name">
<keyword>Widget</keyword>
</keydef>
<topicref href="get_started.xml"/>
</map>
and:
<map>
<title>Using the Gadget</title>
<keydef keys="module‐name">
<keyword>Gadget</keyword>
</keydef>
<topicref href="get_started.xml"/>
</map>
So what would happen if you were to have a referenced topic that includes the following in it?
<ph keyref="module-name">
How would it be resolved? According to DITA 1.2 there can only be one resolution for the processing scope, and it should be the first such value that the DITA-OT encounters when processing the map, with the bottom line that you cannot use a topic multiple times and have a different value for a given key. This is frustrating because it is impossible to use keys in a way that maximizes content reuse—why use multiple keys when all you want is the same key reflecting different values?
Trouble in the Key-ndom Solved with DITA 1.3
What DITA 1.3 brings with it is the ability to “scope” the keys using the new keyscope attribute, meaning that different key values can be supported at different locations within a map. So if you have a topic that is being reused, you can specify different key values depending upon which sub-map that topic appears in.
Using the previous code examples, you could have the first mapref set to keyscope=”widget” and the second to keyscope=”gadget”, you could then expect any topic referenced by each map to resolve to the intended value. Leigh showed us how this could work:
<map>
<title>Training Courses</title>
<mapref href="widget.ditamap" keyscope="widget"/>
*<keydef keys="module‐name"> = Widget
<topicref href="get‐started.xml"/>
<mapref href="gadget.ditamap" keyscope="gadget"/>
*<keydef keys="module‐name"> = Gadget
<topicref href="get‐started.xml"/>
</map>
* Not the actual syntax; abbreviated to save space
So in this case if you used:
<ph keyref="module-name">
within a topic in the first sub-map, it would be resolved as “Widget”, and in the second as “Gadget”.
Leigh then went through several other examples showing how keyscopes ought to behave under different circumstances. So how will keyscopes be useful to Information Architects? It will be good for deliverables comprised of a multitude of submaps; each map can have its own set of key definitions. Additionally, if a topic is re-used within a deliverable, you can specify different key values depending in which sub-map that topic appears. Her presentation was a great way to end the conference on a high note, as she brought some much-needed clarity on the subject. Leigh’s full presentation is publicly available on SlideShare.
A special thanks to Leigh for letting me use her code examples for this article.
