Skip to main content
DITA

An incomplete puzzle: DITA OT stylesheets

A recent post on the dita-users Yahoo group asked how to customize the DITA OT stylesheets in view of the fact that there isn’t much documentation available.

From my work customizing and otherwise perverting the DITA OT, I can sympathize with these frustrations. When I started investigating OT customizations, I found many well-crafted tutorials on how to customize and specialize the OT. These were a great starting point, but they only got me so far. In its current state, the documentation is an incomplete jigsaw puzzle; the trees and buildings are filled in nicely, but the sky is still waiting for someone with patience. (Block that metaphor!)

Because there is no documentation available at the individual template level, you need to reconsider the task at hand. I look on it as debugging, decoding, or sleuthing. With that in mind, I find the following to be very useful:

  • Find a good visual grep-like utility. I use AgentRansack, a free version of FileLocator Pro (it’s free and amazing). This enables me to locate all files that contain a particular class identifier. The visual aspect of the tool allows me to see the context quickly.
  • Use a programmer’s editor that supports XML and XSL. We use Oxygen. Not only does it help check validity and closes tags automatically, but it also provides a handy sidebar that lists the templates and their modes.
  • Liberally spread <xsl:comment> or <xsl:message> directives through the stylesheets you’re examining. That helps figure out where you are. Use <xsl:value-of> or <xsl:copy-of> to figure out what you’ve got.
  • Once you’ve figured out what happens in one of the OT templates, add comments. Now the next time you come back to it, you won’t waste time.

Probably the best form of documentation that the OT could provide here is additional comments in the stylesheets, particularly about the order of processing. I find I add many comments about where to find the template that handles nodes from an <xsl:apply-templates> directive.

One further note. On Tuesday, September 23, I’ll be presenting the third of our “Best Practices in Structured Authoring and Publishing” joint Webinar series with JustSystems. In this presentation I’ll describe a number of approaches you can use to customize DITA OT output. For more information, visit the JustSystems web site.

Simon Bate
September 5, 2008
Read More
DITA

The hidden costs of DITA

Originally published in STC Intercom, April 2008

DITA is a free, pre-made XML document structure. That statement can lead to a few erroneous assumptions: if it’s free, then it will cut down on costs, and if it’s pre-made, it will cut down on labor. There are several things to consider when choosing a DITA solution. Does your staff have the skills to author in a DITA environment? Will additional training be required? Does DITA even match your content model, and if it doesn’t, is it worth the effort to change?

Sarah’s conclusion? “DITA may be free, but it’s not cheap.”

Sarah O'Keefe
April 19, 2008
Read More
Opinion

Somebody does NOT like DITA

From Jon Bosak’s closing keynote at XML 2006:

Another ancient subject that seems to be popping up again is the idea of modular document creation. This is one of those concepts that comes through about once a decade, seduces all the writing managers with the prospect of greater efficiency, takes over entire writing departments for a couple of years, and then falls out of favor as people finally realize that document reuse is not a solvable problem in document delivery but rather an intractable problem in document writing — which is, how to retain any sense of logical connection between pieces of information while writing as if your target audience consisted entirely of people afflicted with ADD.

I don’t think I agree completely, but he does have a point.

I could go on at length about this, but instead I’ll simply leave you with the observation that my personal love affair with modular documentation occurred in 1978 and that I haven’t seen a thing since then that would change the conclusions I reached about it almost thirty years ago. This is not to say that I’m trying to discourage the technical writing community whence I came from their enthusiasm for the modular authoring technology du jour, since engagement in such efforts is virtually guaranteed to buy tech writers a few years in which they can act like software engineers and present themselves as engaged in cutting-edge informational technology development rather than plain old technical writing. That strategy has worked great for some of us.

I think perhaps the arguments for and against single-source publishing are a better place to look. There is a school of thought that argues that single sourcing results in inferior deliverables, both in print and online. But the cost savings from single sourcing are so compelling that nobody really argues for hand-crafting printed and online materials separately any more. (Based on my experience, I think that the quality difference between material that is single sourced (well) and material that is hand-crafted (well) is quite small; perhaps around 10 percent. But that last ten percent is extremely expensive.)

With XML/DITA/modular documentation, there is a similar cost argument. Document reuse and especially localization workflows benefit from modular documentation. For localization teams, getting content in topics rather than monolithic books can result in incremental localization and thus the ability to “sim-ship”; to ship the product in the source language and target languages simultaneously. This, in turn, means a global product launch and a shorter wait for revenue from the markets for which localization is required.

Thus, requirement to accelerate product deliverables and save money on localization (because of more efficient reuse) are going to drive implementation of modular documentation. The argument that non-modular documentation is better documentation will become irrelevant.

Sarah O'Keefe
January 11, 2007
Read More
Webinar

How CompTIA rebuilt its content ecosystem for greater agility and efficiency (webinar)

After an acquisition, CompTIA faced the challenge of unifying multiple content systems, editorial teams, and delivery formats. To tackle this, they implemented a centralized, structured content model supported by a robust content management system. This webinar details how CompTIA overhauled its content operations from strategy through implementation without a pause in production.

Now we’re going to start seeing the true benefits of working in DITA, which is what I’m most excited about. We can maintain our content easily and focus on where things are changing versus converting, rearranging, or recopying content. I’m excited to see how our efficiencies gain as we move into our refresh cycle.

— Becky Mann

Bill Swallow
July 7, 2025
Read More
AI Webinar

Ready, set, AI: How to futureproof your content, teams, and tech stack (webinar)

Your customers expect intelligent, AI-powered experiences. Is your content strategy ready for an AI-driven world? After a popular panel at ConVEx San Jose, the team at CIDM brought the conversation online in this webinar.

AI is going to require us to think about our content across the organization, across the silos, because at the end of the day, the AI overlord, the chatbot is out there slurping up all this information and regurgitating it. The chatbot doesn’t care that, for example, I work in group A, Marianne’s in group B, and Dipo’s in group C, and we don’t talk to each other. The chatbot, the world, the consumer, sees us all in the same company. If we’re all part of the same organization, why shouldn’t it be consistent?

— Sarah O’Keefe

Christine Cuellar
June 23, 2025
Read More