[This article was original published in two parts on the IXIASOFT website back in April 2016. Here’s Part 1 and Part 2. This version on DITAWriter adds some minor updates and brings the two pieces together as a single article. I have also back-dated this blog closer to the time of the conference, purely for chronological-post reasons].
The annual Content Management Strategies/DITA North America conference has become the event to attend for anyone wanting to learn about the latest significant developments in the world of DITA XML. This year’s conference was held in Reston, Virginia, a relatively sunny and warm enclave for those of us coming down from IXIASOFT HQ in Montreal and its Toronto branch office.
The “big deal” at last year’s conference was definitely DITA 1.3. But this year the hot topic was Lightweight DITA, with a whole mini-track of presentations dedicated to the subject running on day one. Other mini-tracks included multiple sessions focusing on creating DITA taxonomies, Agile and DITA (in which I participated), plus DITA and localization.
Having a series of presentations along a common theme was one of several innovations at the 2016 conference, along with the “Newcomer’s Diving Lessons” session Sunday afternoon, and the “Test Kitchen” where DITA software and service vendors could demonstrate their latest and greatest for those who were interested in learning more about what they had to offer.
Communicating Effectively in the “Web of Differences”
This year’s keynote speaker was David Weinberger, author of the famous Cluetrain Manifesto, whose talk was a definite hit among attendees. His presentation, “Knowledge for the Networked Age”, explored ideas of how information and knowledge is disseminated on the Internet and how it has changed how we think.
One statement he made near the beginning of his talk that stood out for me was that our sense of understanding “assimilates the novel to the familiar”. As we learn of new ideas, facts and experiences, each of us adds this information incrementally to our own unique worldview. He then explored the subject of how the Internet functions like an “echo chamber” for many, reflecting back the views of the reader, and how this has been a growing concern for many. But then he pointed out that in this connected age “knowledge is never fully settled”, whereas in the past there was acknowledged wisdom from accredited experts.
Pre-internet print publishers had to delve into a slush pile of content and skimmed the cream; these days the entire slush pile is available to everyone, unfiltered. While the lack of filters might be a matter of concern – as David pointed out with his example of users in online forums: “any group large enough has at least one expert in it”. As a result, we are now seeing knowledge at every scale, even though it is often “messy”.
From a technical writing perspective, content creators are now only one voice among many advocating for the use of products or services they are talking about. And the thing about messiness is that, as David went on to say: “it scales like crazy, and messiness scales meaning”, so that those who are seeking information are more likely to find the expert sources even while starting at the fringes of a conversation. The take-away for the content creators is that we need to ensure that we deliver “the right information to the right people at the right time”. The keynote reinforced what many of us already know: content that is not properly aimed at users or does not convey what they need will inevitably be lost.
What to Expect with Lightweight DITA
IBM DITA Technology Strategist Michael Priestley kicked off this mini-track with his presentation, “Lightweight DITA: A pre/overview“. The title refers to the fact that Lightweight DITA (LW DITA) has not actually been officially released yet, but as Michael explained, we have a good idea as to its general shape and intent. Michael started out by saying that while DITA is definitely growing, it is facing some adoption challenges. Some believe DITA is simply too complex, too hard to customize, and think that learning its fundamentals comes with a steep learning curve.
For many software developers, XML is considered to be “old hat” and are more likely to be familiar with other coding disciplines, such as JSON, Markdown, or even HTML. As Michael explained, part of the idea behind LW DITA is to simplify the existing model, no longer making it reliant on XML, establishing Lightweight DITA as the cross-format content standard. He looked at use cases where having a stripped-down version of DITA might help other organizations within a firm, like how a marketing team could use shared DITA content in product overviews, or how a training group might find the assessment topics from the Learning & Training specialization useful.
Michael then went on to outline some of the operating parameters for LW DITA, including a tightened content model that follows a simple pattern: body content containing blocks followed by sections, where sections can have an optional title followed by more blocks of content, and inline elements plus content only in title, shortdesc and p elements.
Attributes are likewise stripped down to their essentials: conditional processing just gets the generic props attribute, conref is available for reusing content, keyrefs are available for both variable content and indirect links, and the smallest set of attributes necessary for doing localization are there. Similarly, block and inline elements are stripped down to a functional minimum. And that’s it. A DITA structure simplified to its essentials. Specialization is made easier in LW DITA, based on a template-like structure that allows you to annotate it with the specialized elements and attributes needed.
Michael emphasized that this is still a work-in-progress, with nothing set in stone as of yet, while also mentioning that several of the XML editor vendors at the conference had demos of their editor implementing a draft version of LW DITA.
XML Haters Gonna Hate, DITA Players Gonna Play
One of the key drivers of LW DITA is to ease the adoption of structured authoring by those who do not need all of the features of DITA XML. DITA has repeatedly proven itself to be reliable, powerful, customizable and well-supported. But HTML5 is easy. So why not combine the best aspects of the two? This is where “HDITA”, an HTML5-based version of DITA comes in. Professor Carlos Evia of Virginia Tech decided to use HDITA in a study evaluating the perceived complexity and difficulty of DITA fundamentals with a group of technical writing students who had no previous experience with DITA. He started off his presentation by saying that with the success of DITA, there are inevitably still those out there who believe “XML sucks“, and therefore DITA and its fundamentals are also bad. Or as Carlos put it more succinctly: “haters gonna hate”.
In his study, Carlos sought to answer two questions:
- How do novice technical writers evaluate the complexity and difficulty of the HDITA authoring process?
- Can novice technical writers author effective topic-based technical content in HTML5 (HDITA) without full knowledge of XML (DITA)?
He took a group of technical writing students to represent a population of novice authors. In Carlos’ experience, only some of the would-be technical writers who take his “service course” will end up being full-time writers, but most won’t. The latter group is Lightweight DITA’s core audience, and so his test subjects can be considered to be equivalent to those who might be asked to write DITA content as subject matter experts.
His study involved 18 students, ranging in age from 19 – 29, two thirds male, one third female, and five were non-native English speakers. They came from a wide variety of disciplines, including mathematics, computer science, electrical engineering, biology, dairy science, theatre arts and even poultry science. They were instructed on the basics of HTML5, HDITA, and using the Jekyll editor with GitHub. Then they were asked to write instructions aimed at first-year college students on how to use LibreOffice. At the end of the study, Carlos had the quality of the instructions evaluated by another group of students, and also asked the original group as to their impressions as to how difficult HDITA was for them.
The content was rated highly in terms of being easy-to-use and easy-to-understand by the group of evaluating students, who used a standardized scoring-guide for assessing the quality of technical information. The would-be technical writers found writing in HDITA to be relatively easy, and in fact had more issues understanding how to work with GitHub. While the study size was small, the results show that not only is the idea of HDITA as a lightweight variant of full DITA viable, but that the fundamental concepts behind DITA are not hard to learn and need not be bound exclusively to XML.
(For more information on this study, see “Structured Authoring without XML: Evaluating Lightweight DITA for Technical Documentation,” by Carlos Evia and Michael Priestley, published in the February 2016 issue of Technical Communication from the Society of Technical Communicators).
Making DITA Maps Conditional
Chris Nitchie of Oberon Technologies delivered a presentation intriguingly titled “A DITA Map is More than a ToC”. He started out by saying that a Table of Contents (ToC) is only one possible representation for a DITA map, and that the real way to think about them is as a “relationship manifest”. A DITA map is comprised of a manifest of nodes and their properties, with each topicref element representing a distinct node, and the map as a whole describing the relationship between those nodes. Accordingly, other relationships and organization structures can be modeled as DITA maps, including such things as flow charts, mind maps, organization charts and UML diagrams.
As an example of this, Chris first showed an example of a flowchart outlining a car maintenance procedure. In this case it guides the user through a series of steps, and the steps that are followed are based on the car’s Vehicle Information Number (VIN), which identifies its make and model. Wouldn’t it be cool if we could query that information directly and then provide the correct set of instructions specific to a car?
Chris showed how this might be possible by automating the decision points from within a map using real-time information that gathers not only information on the car automatically, but also anything else that might be pertinent, such as the user’s identify (which can determine if it is an expert mechanic or a novice owner working on the vehicle), their location, date, and so on. If conditions can be inserted into the DITA map, it should be possible. Based on Nitchie’s sample code, a conditional DITA map that could query an external resource and deliver the correct topics might look something like the following:
<choose>
<when>
<condition>
<starts-with keyref="car/vinNumber" value="ABC123"/>
</condition>
<mapref href="ABC123_Task1.ditamap"/>
</when>
... [other possible conditions]
<otherwise>
<topicref href="noMatch.dita"/>
<end value="noMatchingTask"/>
</otherwise>
</choose>
[Sample Conditional DITA Map Code]
Through these means it should be possible to “map” out the possible scenarios and retrieve remote information to automate which topics are delivered to the user. The choose/when/condition sequence does not yet exist in standard, non-specialized DITA, but Nitchie was able to show that this is feasible by demonstrating a live demo of his code in action, using a form to input the VIN. I found this a very interesting presentation, especially since the idea of making DITA maps conditional struck me as an obvious idea. Conditional DITA maps would not only allow content creators to deliver material customized to the needs of the user, but could also be a mechanism for retrieving information remotely. This would squarely place DITA as an effective communications layer within the burgeoning Internet of Things.
I spoke briefly with Chris after the presentation, and he said that his company is definitely interested in this idea and plan to run with it. Stay tuned!
What to Expect with DITA OT 2.x
Robert Anderson from IBM gave an entertaining talk about the ongoing development efforts for the DITA Open Toolkit (DITA OT). Normally the words “entertaining” and “DITA OT” are rarely heard in the same sentence, but Robert managed to pull off an informative and fun presentation about what’s happening with the DITA OT.
Robert first talked about the history of the development of the DITA OT, and how supporting the legacy 1.x versions is building up considerable technical debt, as there are increased maintenance costs for outdated functions, an overall reduction in code quality over time, and how innovation becomes more difficult. He summed up this point by saying: “How do you build a jet pack if compatibility rules mandate use of an existing coal based fuel system?” DITA OT 1.8.x, from 2014, would be the last release to preserve any outputting legacy with previous 1.0 releases. So the move to DITA 2.0 was to ensure that we get the “jet packs” (in terms of features) that we deserve.
(Original image from Science and Invention Magazine, February 1922).
What came with DITA OT 2.0? The new dita command for launching output builds from the command line, preview support for DITA 1.3 features, better processing speed for PDF and documents containing keys, and the code base updated to XSLT 2.0. These highlights along with 40+ additional features provide compelling reasons to move to DITA 2.x. Subsequent releases focused on additional support for DITA 1.3 features, bug fixes, and considerable updates relating to PDF output. One piece of output trivia that I was previously unaware of was that the hand-with-pointing-finger that was the default leading symbol prior to any use of the note element has been removed, as some languages consider the symbol to be rude. (Who knew!)
Robert revealed that the next release of DITA OT (2.3) will include further optimizations, improved support for HTML5 output, and additional PDF refinements including indexing, NLS and FOP 2.0. As for DITA OT 2.4, he heavily hinted to expect something by DITA-OT Day 2016, which will be held in Munich this November. Who knows, it may involve jet packs.
Updating the dita.xml.org Website
One of the final sessions that I attended at the conference was that co-hosted by JoAnn Hackos and Mark Poston of Congility about the redevelopment of the dita.xml.org website. This is a project that I have taken an active interest in, and not only wanted to see the live demo (based on DITAweb), but the reaction from the audience, as well. JoAnn began by briefly describing how the original goal for the dita.xml.org website was designed to be the place to head for expert advice and knowledge on DITA, and how it has fallen into its current sorry state thanks to spam. The consulting firm Mekon approached the members of the OASIS DITA Adoption Committee and proposed moving the content and management of the old Drupal-based website to DITAweb. Mark continued from this point, describing how Mekon initially had plans for a wholly new website called DITA Gurus, but realized that they might be able to combine their efforts along with those of the DITA Adoption Committee members to revive the website.
The revamped dita.xml.org website is still very much under construction, but Mark gave a demo of some of its basic functions. The DITAweb web platform takes native DITA content and publishes it as webpages. Mark showed some sample content, such as some white papers that were authored in DITA. He also discussed the development of the taxonomy for the website, which is expressed as metadata within the topics and can be sought by using the search engine built into the platform. This allows the user to more easily find the content they are looking for. Though still in a preliminary state, the draft website (not yet available for the public) got a big round of applause at the end of the talk.
Goodbye, Reston!
The conference was well attended, and CIDM announced the next major conferences they have planned, with Best Practices to be held in Santa Fe, New Mexico from September 12-14, and DITA Europe returning to Munich November 14-15, 2016.
On a side note, IXIASOFT held a Customer and Partner Appreciation Dinner during DITA NA, that I was invited to and which was very well attended. It was great to spend time in person with all of our customers as well as industry experts like Kris Eberlein and Joe Golner over an excellent meal. As one person commented to me, the mass exodus of people heading out the door together almost seemed like a very orderly (and happy) evacuation of the entire hotel. Thanks to everyone who joined us that evening!
