For technical writers, extensible markup language (XML) is a lifesaver. It helps us deliver high-quality technical documentation by applying consistent style and structure to our writing. By using XML, we create single-source documentation that can then be delivered in multiple formats by applying stylesheets.
A stylesheet is a set of rules that describes how to format a document. As technical writers, we tag the text to change how it displays in the output, but our decisions aren’t based on visual appearance (that is, we don’t say ‘Make this text bold, and make this text italic’). Instead, XML tags are semantic. We mark text according to its meaning in the document structure (for example, ‘This text is a section heading, and this text is a button on the UI.’)
When the document is published, the stylesheet determines how each element appears in the output. With this approach, a single source document can be published in multiple formats, with the output tweaked to best suit the format. The stylesheet for a printed handbook can be different to a version published online, even though the content is the exact same.
Some Background
As you can imagine, tagging technical documentation can get very complex. We don’t want to write in raw XML when there are XML authoring tools that make the writing process easier. As part of a client project involving the development of courseware for delivery in multiple formats (classroom and virtual instructor-led training, as well as independent e-learning), we’ve been working with two such tools in parallel: SDL Xopus and PTC Arbortext.
The courseware we’re working on follows DITA standards. DITA is a model for XML-based authoring and publishing, where larger documents are broken into smaller chunks (or topics), each a separate XML file. Because of this, working in DITA is made much easier by using a content management system (CMS) to track those files. In this project, both Xopus and Arbortext plug into the same CMS and work with the same files. It’s a perfect setup to compare the two and see which XML authoring tool is better in this particular context.
Introducing the Contenders
In the blue corner, we have Xopus: a nimble, browser-based editor that runs directly from the CMS.
In the red corner, we have the challenger: Arbortext. It’s a heavier program, one that requires installation on your machine and local copies of files to work with.
Is that extra weight a help or a hindrance?
Round 1: Getting Started
The browser-based nature of Xopus makes it simple to get going. From the CMS, click once to start editing a file. When you finish, click again to check the file back into the CMS. Arbortext is slower. You need to download the file from the CMS, open it in the tool locally, then check it back in. It’s a fairly smooth process – but it’s still more complicated than Xopus. This round is over quickly, with a clear winner.
Our winner in this round of Xopus vs Arbortext: Xopus
Round 2: Speed and Staying Power
Xopus starts quicker, but it’s temperamental. Prolonged use eats up memory, especially with large files, and errors start occurring if you don’t clear your cache regularly. This isn’t a critical problem, as it becomes second nature to keep an eye on your memory usage and restart the browser when the numbers creep too high. But it is very frustrating when the application gets sluggish, especially when it starts taking several minutes to perform very small tasks.
Arbortext is more solid. Once you download files, you can open and edit them quickly. However, it’s not flawless. A couple of writers found bugs where entire documents suddenly appeared empty when checked in to the CMS, resulting in a loss of work.
To be fair, some of these problems lie in the interaction with the CMS rather than in the tools themselves. But on the whole, it’s undeniable that Xopus is less steady on its feet than Arbortext.
Our winner in this round of Xopus vs Arbortext: Arbortext
Mid-Bout Break
Two rounds down and both contenders have taken a victory. Who’ll be the winner overall? Come back soon to read our final thoughts on Xopus vs Arbortext.
For now, what do you make of our synopsis, and what’s important to you in an authoring tool? Let us know in the comments below.
