When you’re evaluating a move to a DITA-based solution, you naturally want to know of the many benefits it provides. But you also need to know DITA’s costs.
A few of the ongoing costs associated with doing DITA are included in the slide series, When is DITA Right for You?. But at the time I created that presentation, I was focused primarily on DITA’s benefits, and how to structure our documents to achieve them. I just assumed that the free “Open Toolkit” would handle document generation.
Since I focused mostly on DITA’s benefits, and was unaware of the major costs, the presentation was naturally a bit rosy-eyed. This article “redresses the balance”, so to speak.
But by far the biggest issue with DITA is that the free, “Open Toolkit” simply does not work for production-quality output. It has too many bugs. To overcome them, you need either a $1500-per-seat editor that lets you output one document at a time, or an uber-expensive CMS system ($100k a year minimum, in general) that lets you generate an entire suite of documents.
One of the reasons those systems are so expensive is that they have solved the production bugs.
If you have a huge document set with a lot of variations then, you’ll need the expensive CMS — if only to generate documents. If you can live with generating one output a time, the editor is the way to go. But if you have a lot of writers, the expense adds up fast.
At one point, I found an inexpensive CMS that might have worked. But it was completely undocumented. The authors of that system were willing to act as consultants. So that option, alas, also led to major expense.
The only viable option, then, was to solve the production problem myself. But the problem was that after spending 9 months learning how DITA works and working on our document structures, I had three months left in which to solve the production problems, and a budget that wouldn’t let me buy my way out of the problems.
The design option I really liked was to use it to generate plain HTML, use DreamWeaver templates for output styling, and find a conversion program to generate PDFs from the HTML, when needed. Got close to getting it to work, too! Not close enough to save the project, though. So the effort went down in flames, thanks to some adroit politicking by the opposition, who promised the same benefits with their tools. (The promises were entirely imaginary, of course, but it took deep knowledge to know that.)
I got as far as designing the system, and building the major tool I needed to implement it (RuDi – A Ruby-based System for DITA document generation). That was rXSLT — an XSLT transformation engine implemented in Ruby, so it looks a lot like XSLT for straight transformations, but with the advantage that you can escape to Ruby to write conditionals and loops, which are extremely difficult in XSLT.)
The benefit of that tool was that it would make it possible to fix Open ToolKit bugs in post-processing, and convert the generated HTML documents into DreamWeaver template-based documents.
That implementation was designed to solve the second problem with the DITA Open Toolkit — to change output styling, you need to modify the build system, which means that even small styling changes have the potential to destablize the build.
With the intended system, a template designer could instead use the DreamWeaver WYSIWYG editor to customize the Look and Feel, without ever touching the build system.
All of that seemed like it was worth doing, of course. But as I mentioned, I ran out of time. And while I generally do “document first development”, I was in hurry. So when I look back on the RuDI project now, I’m hard pressed to figure out how rXSLT works, or how to use it!
That information could undoubtedly be recovered in a few weeks, after which a tutorial could be created — but it’s only worth doing for someone who a) has the time, b) has the need, and c) believes in the design!
Copyright © 2017, TreeLight PenWorks
