The Darwin Information Typing Architecture (DITA) provides an XML architecture for technical communication. Although implementing DITA is likely to be faster and easier than building your own XML architecture from the ground up, DITA is not suitable for everyone.
published in STC Intercom, March 2011
A standards-based workflow is challenging. This article discusses the issues with DITA (an XML standard for technical communication content) and XSL-FO (Extensible Stylesheet Language Formatting Objects, a standard used to create PDF from XML (http://www.w3.org/standards/xml/publishing).
In this webcast hosted by Scriptorium, author Tony Self discusses his new book, The DITA Style Guide, and how it fits into a DITA workflow.
In this webcast, Sarah O’Keefe discusses the challenges of getting attractive output from DITA and demonstrates Scriptorium’s approach to web-based help and PDF.
In this webcast, Sarah O’Keefe discusses how to calculate the return on investment of an XML/DITA implementation for technical content.
If you are considering XML and DITA, but are trying to figure out whether you can justify the cost and effort, this session is for you.
Whew! Now I know how St. George felt after slaying the dragon. I’ve defeated the Mark of the Web beast and have lived to tell about it.
The DITA Open Toolkit comes with support for many languages, but you can always find one that is not yet covered. Fortunately, adding a new language does not require any strange incantations.
In this webcast, Sarah O’Keefe of Scriptorium surveys DITA’s publishing options and weighs their practical implications.
Many content management systems (CMSs) take over the responsibility of file naming. For the most part, this is fine and is actually necessary for maintaining cross-references and conrefs within the CMS. When you use the CMS to build a DITA map, the CMS uses its own names in the <topicref> elements.
The other day I had to convert a large table from Word to DITA. I started looking at Word XML output and thought about transforming it with XSL (which I have done in the past), but that seemed to be too much trouble for this document. Then I remembered a technique an old SQL coder showed me for loading large amounts of data into a SQL table. I realized this technique could be readily adapted to DITA.
Simon Bate of Scriptorium Publishing introduces specialization in the DITA open toolkit and walks viewers through the fundamentals.
published in STC Intercom, May 2010
A condensed version of Creating PDF files from DITA content.
Download the PDF 
(130K)
There are numerous alternatives for producing PDF output from DITA content. The approach you choose will depend on your output requirements—do you need images floating in text, sidebars, and unique layouts on each page? How often do you republish content? How much content do you publish? Do you need to create variants for different audiences? Do you provide content in multiple languages?
This webcast demonstrates using the DITA-FMx plugin with FrameMaker 9 to author, edit, and create output from DITA content. Topics covered during the demo include creating DITA topics using different options and templates and generating a book from the map and then saving to a PDF file.
The Darwin Information Typing Architecture (DITA) is being positioned as the solution for XML-based technical content. Is DITA right for you?
This white paper describes the potential business advantages of DITA, provides a high-level overview of DITA’s most important features, and then discusses how you can decide whether to develop a DITA-based XML implementation.
When you implement a DITA-based workflow, you face myriad new challenges, such as getting accustomed to topic-based writing, exploring reuse strategies, and specialization. The most difficult technical obstacle is usually setting up a PDF/print publishing workflow. The DITA Open Toolkit provides very basic PDF output, but for organizations who require attractive, professional-looking PDF content, extensive and expensive customization is required. FrameMaker is easier to configure than the Open Toolkit and produces lovely PDF files, but can you work around the limitations of the DITA support? InDesign offers the highest quality typography but has significant limitations in working with structured content. This session discusses the advantages and disadvantages of each approach to extracting PDF from DITA content.
This session is intended for individuals who are considering a DITA implementation and expect to need PDF output. Basic familiarity with DITA, XML, and related technologies is helpful but not required.
NOTE: During the recording, the presenters will mention polls. You will not see these polls while viewing the recording, but the presenters will describe the results.
When you’re considering tools for authoring DITA content and creating output, there are many choices to evaluate. To make your journey toward DITA implementation easier, Scriptorium is offering free webinars in early 2010 to show you how three tools handle DITA-based information.
Odysseus in front of Scylla and Charybdis by Johann Heinrich Füssli (Wikipedia)
On January 19, Sarah O’Keefe will show you how MadCap Flare supports DITA constructs, and on February 16, Simon Bate will demonstrate the DITA features in the oXygen XML editor. On March 16, Scott Prentice of Leximation will demonstrate how the DITA-FMx plugin works with FrameMaker 9.
As an added bonus, attendees can win a free license of the tool shown during each demo! For more information about these sessions and to register, visit our events page.
If there are other topics you’d like to see covered in later free webcasts, please send suggestions to [email protected].
Unabashed plug warning: The following entry gives a conceptual overview of a solution Scriptorium has implemented for managing trademarks in structured tagging. And we’re proud of it.
You know the problem. According to your style standards, only the first instance of a given trademarked term should display the trademark symbol. Structured documentation allows you to re-use document parts (such as DITA topics) in just about any order you like. In Manual A, the first file containing the trademarked text is, say, Topic A; in Manual B the first file containing the trademarked text is Topic E, which is also used in Manual A. Where do you put your trademark markup, and how do you maintain it when running Manual A and Manual B at approximately the same time?
Maintaining the trademarks by hand adds a level of effort that becomes non-negligible when you start considering a large number of manuals. And the process becomes error prone – those darned human beings. Different writers might tag things different ways, trademarks might escape notice, or markup might be inserted in inappropriate places by accident.
Isn’t this one of those problems that automated documentation was supposed to solve, not create? I once had a professor who said that computers were supposed to handle the work that computers could solve so people could work on the problems that only people can solve.
More than one of Scriptorium’s customers has presented us with this problem, so we know it is not uncommon. We have found a way to deal with the problem in DITA, and we believe that the principle is sufficiently generic to use in non-DITA structures as well.
To begin with, forget conditional processing. It won’t help you with the problem of marking only the first instance of a term. In the example of Manual A, above, setting the condition “Manual A” would still display the trademark in Topic A and Topic E. This is not what your editor wants – and he or she will let you know it in spades if he or she is any kind of editor at all.
Scriptorium’s solution for DITA, in simple outline, is as follows:
Using XSL, go through the ditamaps and remove all trademarking from the document files.
Following a predefined list of trademarked and registered trademarked terms, go through the ditamaps and identify the files that contain each term. Create a temporary file that lists the relevant files in order of book occurrence. (This step prevents having to crawl through the ditamaps more than once.)
Using Perl, iterate through the files listed for each term in the temporary file. Check the occurrence of each instance of the term, in text order, and evaluate whether it is a valid occurrence that requires trademarking. If so, wrap the appropriate trademark markup around it and go to the next trademark. If not, keep going through the text and the list of files until you find a valid occurrence of this trademark.
We possibly could have used XSL instead of Perl for the third step, but Perl’s text manipulation capability is much more robust than XSL’s, so we chose Perl.
In the implementation, the trademarking utility is coordinated by an Ant process. A user runs this utility just before the book is rendered for output. Being in Ant, the trademarking process could probably be integrated into the DITA Open Toolkit build system fairly easily to create a seamless, one-step production process.
There are a number of interesting problems that arise during implementation. For example, in step 3 the process has to evaluate whether the instance of a term is valid for trademarking. Some kinds of non-valid instances of a term in the text might be:
The term is in an indexterm tag.
The term is in an href attribute.
The term is in a title.
The term is in a codeblock tag.
You might also encounter a condition where a trademarked term could be both mixed case and all uppercase. Per your style guide, only the first instance of either should be marked, but not the first instance of both. That sort of requirement makes life just a little more interesting for a coder.
In general, the issue of trademarking first instances is not a simple problem to solve, and variations in style requirements will undoubtedly add complexity and challenges to the problem. But that’s what automated documentation is supposed to be good at, right? So we humans can get back to doing the more difficult problems that only people can solve.
I’m not sure – is that really such a good deal?
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:
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.
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.”
Download the PDF (950 K)
