Considering the true costs of customized structures: DITA specialization

Alan Pringle / Case study5 Comments

Man with magnifying glass photo by Casey Fleser

Balancing the standardization of structured content against creative requirements is not just about formatting. When companies choose an XML standard, such as DITA or DocBook, they must evaluate whether to use the default structure or modify it to better fit requirements. The discussion about such changes is a creative process itself. When should a company change default structures?

This is the third of three case studies about balancing creativity and standardization in XML workflows. This content first appeared in tcworld magazine.

A company implemented DITA to improve the control over conditional content, support responsive designs for phones and tablets, and manage increasing localization requirements. Content was previously developed with desktop publishing software and distributed in print and PDF. Guides contained procedures with more than 100 steps, which included substeps and sub-substeps.

By default, the DITA standard does not permit sub-substeps in the task structure. The content creators requested the addition of a sub-substep element.

Scriptorium’s information architects suggested evaluating the efforts required to either modify or maintain the default structure.

man using magnifying glass

Evaluate structure customizations from every angle (flickr: Casey Fleser)

Modifying the default structure (through a process called specialization) would entail the following work:

  • Developing and testing the structure customization
  • Implementing the change in authoring tools, the component content management system, and stylesheets for each type of output (PDF, HTML, Help systems, etc.)
  • Distributing the customization to localization vendors and ensuring their tool chains support the change
  • Training new writers familiar with the default structure on the customized structure

Preserving the default DITA structure for the procedures would require the following effort:

  • Rethinking the structure of procedures so that they did not include sub-substeps
  • Rewriting many procedures to follow the new methodology, which would break up lengthy procedures into smaller related procedures

The content creators were immediately resistant to the idea of rewriting content to match the default structure. They argued that the effort would be too significant due to the large number of procedures. The writers’ bias against the new approach was likely increased by the perception that rewriting was an implicit admission that the current procedures were poorly structured.

The information architects acknowledged that rewriting the procedures would require great short-term effort. However, they believed that the overall benefits of maintaining the standard outweighed the rewriting effort. There would be no costs for implementing and maintaining structural changes for the company or for its localization vendors. New writers with DITA expertise would not need training on custom elements.

More importantly, adhering to the standard offered compelling long-term benefits. The information architects rewrote some procedural content in the default structure. The samples demonstrated how shorter procedures increased opportunities for content reuse, which would reduce writing time and improve consistency. Also, the information architects believed it was essential to consider users reading content on the small screens of phones and tablets. Phone and tablet owners would more easily comprehend shorter procedures.

Breaking up three layers of steps in procedures to just two layers

Breaking up long procedures into smaller chunks (image by Gretyl Kinsey)

Ultimately, the content creators and information architects were not able to agree on an approach. The structural changes were not implemented in the pilot project to stay within the project’s budget. However, after the pilot was completed, the information development group hired its own full-time information architect and intended to reevaluate the customization with that resource in place. (Not every consulting engagement has a happy, tidy ending, unfortunately.)

About the Author

Alan Pringle


Content strategy consulting. Publishing (electronic and print). Eating (preferably pastries and chocolate). COO at Scriptorium.

5 Comments on “Considering the true costs of customized structures: DITA specialization”

  1. Sub-substeps. Oh. My. Goodness. Just when the political news had me thinking the world couldn’t get any dumber, you’ve proven me wrong. And please tell me that step 105 is just for illustrative purposes, and not part of an actual task titled — I don’t know — “Assembling an aircraft carrier bolt by bolt” or something.

    More than anything DITA-related, what I see here is the effects of corporate culture. Here we have an entrenched writing group — or perhaps just a few individuals within that group — who simply must keep things as they’ve always been. I find it interesting that in this story the business case for change dovetails so well with the usability case. I find it distressing that the team wasn’t moved by either one.

    1. The 100+ steps were very real. And you should be afraid. VERY afraid.

      I think these content creators were ultimately more interested in maintaining the status quo (and control) than doing what was right for their employer and customers. Moving to a new content development process gave them the perfect opportunity to change, and they refused to do so.

  2. This isn’t just about DITA, it’s about effective communication that is suitable for its audience, and it’s about the long term efficiency and productivity of teams. I have seen sub-substeps in the wild (not 104.a.1, but certainly 17.a.1). On one occasion, I silently changed the structure of the doc to multiple separate procedures – effectively eradicating the sub-substeps – and no-one noticed!

    I have also seen resistance to structural change of the kind described by Alan, where short term effort was rejected despite obvious long-term and wide reaching benefits. Sadly that was not a situation I was able to deal with.

    1. You’ve summarized the situation very well. I wish we could have silently eradicated sub-substeps, but we did not own the content!

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.