JoAnn Hackos, CIDM Director and Comtech Services, Inc. President
In his comprehensive review of the Minimalism agenda, Professor Hans van der Meij, keynote speaker at CMS/DITA Europe demonstrated to the DITA crowd that good information design is key. Van der Meij leads a group of student researchers at the University of Twente in the Netherlands. Their current research focus is on the development of successful instructional videos. However, they continue to gather data that shows that minimalism is crucial to good communication.
Van der Meij reminded the attendees that our information consumers come to information with their goals foremost in mind. They are looking for instructions to help them perform tasks successfully and solve any problems they’ve encountered. They want both instructional text and instructional videos to be immediately accessible. In fact, videos should be no more than one or two minutes long. Text should take little more time than that to read and process.
As we heard from the attendees, the Van der Meij keynote was a great success, which was refreshing for a DITA-focused gathering. DITA Europe, as it has developed, is quite a “techy” conference. We have two tracks, one technical and the other business oriented. Generally, the technical track attracts a few more attendees most hours. But as a business-oriented manager, I generally focus on the business presentations—and they were well worth attending as usual.
One particularly noteworthy set of presentations presented two methods of generating DITA maps, the first from Excel spreadsheets and the second from a new, simplified interface. We have long advocated using an Excel spreadsheet not only to plan a single set of DITA topics but to track DITA topics across deliverables. The Annotated
Topic List (ATL) has been part of our project management training and Information Modeling long before DITA and continues to help teams actively manage their content development. Now we have a process, developed by George Bina from Syncro Soft, to transform the topics into DITA files. The transform is referred to as DITA Glass. Dawn Stevens from Comtech Services presented the ATL/DITA Glass transform.
At the same time, Magda Caloian of Pantopix, presented a new transformation to produce a DITA map and stub topics from an Information Model. The new processes uses Trello Outline. In it, the information architect outlines the DITA project, using indented outline items to indicate the hierarchy of the topics. A few small annotations, such as ##t, set the topic types. The transform program, outline2ditamap.py produces the map and all the stub topics.
For people struggling with project planning, information architecture, and map generation, both of these methods provide superb ways of producing maps quickly and easily.
On the technical side of the program, OASIS DITA Technical Committee members Kris Eberlein and Robert Anderson entertained the audience with a frank discussion on the usefulness of DITA keys, introduced with DITA 1.2 and improved in DITA 1.3. They pointed out that same organizations may not need or want to use keys, especially if the tools they use don’t support keys, which is true of some legacy content management systems. But for those that want to effectively manage links and variable text, keys are valuable. Keys make variations in content much easier to manage. And, with scoped keys of DITA 1.3, it is possible to have more than one set of keys working in a map. Be aware, the speakers warned, about making choices that are too complex for your content. It’s still best to keep things simple and reproducible.
Marie-Louise Flacke presented the new DITA troubleshooting topic in the context of improving troubleshooting information in technical content. She pointed to many examples, unfortunately, of really poor troubleshooting, quoting a study that revealed that only a tiny percentage of end users actually understand the error messages they get with software. In an inventory of 100 manuals, Hans van der Meij’s researchers found that one-third had no troubleshooting information at all, half did not mention troubleshooting in the table of contents or index, and fully 86 percent never made troubleshooting information easily visible in the text.
The new DITA troubleshooting topic, as Flacke demonstrated, provides authors with a template for creating sound information to support error recognition and recovery, one of the four tenets of minimalism.
Even as many talked about how to conquer the perceived complexities of DITA, others talked about the challenges of getting DITA accepted by those outside of technical documentation and discussed lightweight solutions. Ray Gillespie of Nokia provided an excellent comparison of lightweight markup languages, such as Markdown and reStucturedText. Although DITA far exceeds these tools in features such as reuse, metadata, and semantic tagging, lightweight markup languages are attractive due to their simplicity, learnability, and familiarity.
We also heard from colleagues leading the charge in implementing DITA within training organizations. Much resistance to DITA from training groups centers around the difficulty of creating slide presentations. France Baril of Architextus demonstrated her solution, which enables authors to select a subset of elements from full documentation topics to populate a slide show and present the results using reveal.js. Brigit Strackenbrook, XStructuring and Emiel Ubink, Thieme Meulenhoff showed how they have expanded the Learning and Training specialization to add additional training topic types and interactions to better meet the demands of the training community.
There were a host of excellent presentations at DITA Europe 2015, and I don’t mean to slight any of them. I enjoyed everything that I heard. I hope to have the same excellent set of presentations at the spring Content Management Strategies/DITA North America conference <https://cm-strategies.com/>. If you’re hoping to present in Reston, Virginia, do get your proposal into the conference website soon. We’ll be making selections at the end of December.