Review of XMetaL Author 5.0 DITA Edition
Click a link below to jump to a particular section; click any "
As a writer who is saddled with the task of creating an entirely new library of technical documentation pertaining to new technologies, I'm simultaneously fascinated with and terrified of structured authoring. I understand the importance of structured content and many of the new architectures, such as DITA. Having worked exclusively in raw XML, I've been amazed by the amount of effort that can go into creating structured content.
Since it will likely be my fate to implement structured content architecture in my own workplace, I was excited by the opportunity to check out XMetaL Author 5.0 DITA Edition. Created specifically to support DITA architecture, XMetaL Author 5.0 is chock-full of intuitive (and occasionally automated) features that make starting out in structured authoring much easier. With this release, XMetaL's developers are striving to make sure that you don't have to understand DITA, XML, or the underlying document structure.
One of the most difficult aspects of getting started with structured authoring and DITA is wrapping your mind around the associated terms and concepts. This section of this article presents a basic overview of what is involved. If you're familiar with structured authoring and DITA you may want to skip to the next section.
Structured authoring is a way of setting up your documentation so that your information is separated from the presentation of that information. Templates are developed so that the information in documents is tagged in a consistent manner. This makes it possible to render the same body of content in a variety of different ways. Scriptorium Publishing Services has a great tutorial on structured content that discusses a recipe as an example of a familiar structured document:
"Consider, for example, a simple structured document-a recipe. A typical recipe requires several components: a name, a list of ingredients, and instructions. The style guide for a particular cookbook states that the list of ingredients should always precede the instructions. In an unstructured authoring environment, the cookbook editor must review the recipes to ensure that the author has complied with the style guideline. In a structured environment, the recipe structure requires the specified organization."
DITA is one form of structured authoring. DITA stands for "Darwin Information Typing Architecture", but you don't really need to remember that. PCMag.com defines DITA as "[a]n OASIS standard for defining online help and support information in XML.... DITA uses a DTD schema that covers "topic," "concept," "task" and "reference" categories."
The DTD is a file in which the structured documents rules are defined - for instance, the DTD defines the names of the elements (tags) that can be used in a document, the element hierarchy, the kind of content that can be contained in an element, and the elements' attributes. A DTD file is usually created using XML and is stored with a file extension of .dtd.
When you create and save files using XMetaL Author, the program constantly references its DTD to ensure that you aren't creating any bad mark-up by inserting incorrect elements or deleting parts of necessary tags (see Validation Log).
If you were forced to create structured content and DITA from scratch, you might find yourself completely at a loss. Fortunately, in XMetaL Author 5.0 DITA, much of the background work is automated, so that writers can concentrate on content without fretting the extremely technical details of the program. That said, XMetaL was designed to allow programmers and content managers to dig in to the nitty gritty, such as playing with cascading style sheet, DTDs, and schema.
Installing XMetaL is as easy as any program should be. Download the files from XMetaL, double-click on the installer, and you are guided through the standard installation procedure. As with most installers, you can choose the location of your XMetaL files or use the default. The installation really is as simply as hitting the Enter key seven or eight times and then filling in the product key. Opening the program is as easy as double-clicking on the desktop icon or selecting the program through your Start menu.
A DITA map is used to manage the structure of topics in a document. In XMetaL, the DITA Map Editor functions in a similar way as the book and chapters tree structure of your average help authoring editor, such as RoboHelp. It's located on a pane on the left side of the screen, and has the same click-to-open functionality that you would expect from a book and chapter tree, but with added functionality. You can also use the DITA map to browse your desktop and open other files by clicking on the Desktop tab below the DITA map.
Figure 1: DITA Map
You can use the DITA map to navigate to topics that have been referenced by the DITA map - however, the topics must FIRST be referenced by the map.
You create a DITA map by clicking File > New > DITA Map > DITA Map.
Figure 2: New DITA Map
You can set the attributes of a DITA map by clicking the Properties button above the Resource Manager. Adjustable attributes include translation language, importance, document scope, print and TOC inclusion, and more.
Figure 3: Properties button
To reference a topic to the map, you must use the menus specific to the Resource Manager (located above the DITA map). In this case, you would choose Insert > Topic Reference.
Figure 4: Topic Reference
You can then use the Insert Topic Reference pop-up window to browse for the topic that you want to reference.
The arrow buttons below the DITA map menus can be used to move topics around, or promote or demote topics (i.e. changing a topic to a subtopic).
The structure view offers an outline of your document. I didn't particularly like using the structure view, as it seemed redundant given that I could already view the documented structure in the document display frame; my sample document was also small enough to not necessitate such a detailed information hierarchy.
For large documents, structure view is what makes structured authoring, well, structured.
The structure view actually only displays the structure of a selected topic. You can have many topics open at once, and they are displayed on tabs that run along the bottom of the screen. Clicking on the tab will display the topic content in the document display pane, and its structure in the structure view.
The DITA map can be used to navigate to a topic that is referenced in the map (by double-clicking on the topic icon), but other topics that are not yet referenced can be open and edited in the structure and document display panes without affecting the appearance or behavior of the DITA map.
Figure 5: Structure View
XMetaL offers four different views of topics. The first, called Normal, is more or less a WYSIWYG view (or as XMetaL likes to call it, a WYSIOO - What You See Is One Option) akin to working in RoboHELP. Of course, what you get actually depends on a number of different factors, including your CSS and DTD.
The Tags on View option allows you to see the XML elements as applied to the document. This is the second most common view used by writers who are creating XML documents. I prefer this view, because the tag display makes the details of document formatting very obvious.
The third most commonly used view is the Plain Text view - the view that I worked in when I initially used XMetaL all those months ago. Plain text is a legitimate view for users who are comfortable with raw XML, but it can be confusing for people who don't enjoy working with the code, and it's also easy to create an invalid document by deleting part of an element tag in this view.
The last view is known as Page Preview, and gives a close approximation of what your document will look like once the content has been generated.
The thing that makes XML so great is, of course, its single-sourcing and content reuse capabilities. XMetaL capitalizes on this feature by offering a simple way to use and reuse content.
Reusable content is a blessing for technical communicators. The idea is that you can create a component - be it a paragraph, a phrase, or a name - and then create a reference for that component.
Let's say you have a step that you use over and over again in a help file, and you want to be certain that this step is consistent across all of your documents. Something like "Click the OK button to complete the process." Before this version of XMetaL, you would write that step down, store it in an XML file, name it with some kind of reference like "last_step", and then use that reference name through the rest of your documentation to call that component.
Reusable content is a great time saver. Not only do you save time by not typing the same sentence or paragraph over and over again, but when a change needs to be made to a reusable component, it only has to be made once, where the component is stored, and it will change across all documentation.
I've used older versions of XMetaL before that were rife with references to reusable components. The problem with this was that the reusable content was stored in 3 or 4 different files in wildly different network locations, and if often took a while to find them when they needed editing. And there were thousands and thousands of reusable content components.
XMetaL Author DITA makes creating and using reusable content very simple. When I worked in pure XML code I would have to create and name a bit of content, create an entry in a separate reference table, and then actually use it in a help file. The DITA version of Author dispenses with such nonsense by allowing you to create and insert reusable content through the editor's graphical interface.
In the olden days, setting up that kind of content for reuse would have taken much longer, often up to several minutes to properly associate content with a particular reference that could be used in the documentation.
With XMetaL Author DITA, you simply type the text, highlight it, and choose Create Reusable Component from the Reuse menu.
Figure 6: Reuse Menu
Next, you give the component a name, select the parameters, and choose whether or not to replace the current typed content with that component reference.
Figure 7: Create Reusable Component window
Each component is saved in its own separate XML file. To insert a reusable component into a document, you simply open the document, insert your cursor, and click Reuse > Insert Reusable Component. You then browse for the component and click OK.
While this is vastly simpler than the old process of creating, storing, and referencing reusable components, I have a few objections to the way it has been designed. My first problem is the issue of naming the XML files. It will be incumbent upon content managers to ensure that a good naming schema is in place. In my old single-sourced XML docs, we literally had thousands of reusable components. The fact that these were stored in a few separate XML files made them, if not simple to find, then at least not horrifically difficult to locate. My worry is that, in keeping hundreds or thousands of separate XML files, it might be difficult to search for the component that you want to reuse in a new document.
Figure 8: Select a reusable component
In addition to creating and using reusable components, the Reuse menu allows you to create conditional text. Conditional text is one of the greatest inventions in documentation, allowing you to create multiple versions of a document out of one document set. For instance, additional instructions for administrators might appear in an admin guide, but not in an end user guide.
When you finally generate content, you can select the conditions that apply to the document you are generating. Click File > Generate Output, and then click the Show/Hide Conditional Text button and select the conditions that you want applied to the document.
To set conditions for text in XMetaL Author, you simply select the text, and choose Reuse > Apply/Remove Conditions. You then select your conditions (from the Audience, Platform, and Product categories) and voila! The conditional text is marked as conditional, through text formatting.
Figure 9: Setting conditions
You can also change the types of formatting for each condition through the Reuse menu as well. Simply click Reuse > Style Conditional Text, and select your formatting from the drop down menus available for each condition.
XMetaL provides a large number of available elements in a convenient list that is easily displayed by clicking View > Element List.
Elements are easily applied to topics in XMetaL - you simply insert your cursor in the topic where you want to place the element, or highlight the text that you want to apply the element to, and double-click on the element in the Insert Element list. The list of available elements changes as you move your cursor around your topic, so that you can't accidentally insert a paragraph element inside a title element.
If you are working in Plain text view, of course, it is much easier to screw up your code by accidentally deleting a bracket. Fortunately, XMetaL's validation log won't allow you to change back to a normal view without first fixing your code faux pas. The log will even point your cursor directly at the offending party.
Like a word processor, you can track changes in XMetaL by clicking the Track Changes button or by clicking Tools > Track Changes.
XMetaL offers the ultimate saving grace for the writing klutz - unlimited undos, regardless of whether or not you have saved the document. So, if you find that you accidentally deleted an important bit of text fifteen tasks ago, you can get it back using Ctrl Z like you would in Word, but with many more undos.
Once you close and reopen the document, however, the undo capabilities are lost.
XMetaL has made extra effort to prevent users from doing stupid things. Stupid things are exceptionally easy to do in XML (or any code, for that matter), and XMetaL wants to keep its users from being unnecessarily frustrated by the details of tags and attributes. Their validation log is one way of preventing major mistakes from becoming show-stopping problems.
When you are working in Tags on View or Normal views, it's pretty difficult to screw up the tags. Tags are designed to be self-sufficient - that is, tags know where they can go, which tags should come before and aft, and inserts them automatically for them. A qualified XML and SGML document expert can change these element settings by editing the DTD.
Smart insert is a feature that prevents you from putting something somewhere that it doesn't belong. If you have your cursor in the middle of a title, XMetaL is not going to allow you to go ahead and insert an ordered list there.
XMetaL will, however, find the next logical place in which an ordered list can legally be inserted. This means that you can be roughly half as careful as you need to be when composing a set of instructions, because XMetaL will be doing a lot of your thinking for you.
XMetaL clearly has it in for FrameMaker, and the RenderX FO engine that comes bundled with the Enterprise Edition lets you easily create PDFs from your XML-based content. I was told that you can download and use RenderX FO with the other Author 5.0 editions, as well.
If you use a content management system, Author 5.0 Enterprise Edition supports connections to any system using XMetaL Connector. According to XMetaL, Author 5.0 can work with virtually any CMS. Because I was not using a CMS to test this product, I was unable to verify the ease of use of this feature, but if it's as easy as the other features, then it should be a snap.
XMetaL's embedded help is comprehensive, and does a decent job of helping newcomers how to create content and generate output, but it is oddly organized. For instance, the first chapter throws you right into Authoring Content, but the last chapter covers the "Welcome to XMetaL" entries. Perhaps the idea is that people should be able to leap into authoring immediately without much wordiness, but it seems like an odd arrangement.
Also, although the User Guide contains a glossary, the help does not. It should.
XMetaL's User Guide, which comes with the software in PDF form, is excellent at general overview, and also delves into a discussion of working with SGML and XML, DTDs and schemas, how to work with mark-up, and what limitations are inherent to working with these back-end files in XMetaL.
Even better, although not necessarily available to your average user, is the XMetaL Author 5.0 DITA Edition Evaluator Guide. Created for people who plan to write reviews of XMetaL, the Evaluator Guide actually gives a quick rundown of the product that explains the features without overwhelming the novice.
If your company is considering structured documentation using DITA architecture, then purchasing XMetaL Author 5.0 DITA Edition might be the easiest way to get started. Because the DTD, CSS, and other backend files are already configured for out-of-the-box use, you can get started creating structured content right away.
The XMetaL support/sales personnel that I spoke to mentioned that for large companies with specialized documentation, it's not uncommon to hire a contractor or specialist to handle the backend work, such as changing elements and element hierarchies. If you feel comfortable tackling these tasks, more power to you, but they usually are performed by someone who has in-depth understanding of SGML (Standard Generalized Markup Language).
I am considering purchasing Author 5.0 DITA for my own publications department, because I believe that the layout is simple enough to allow a wide range of users to easily grasp the technology. Since my own documents require frequent content reuse, Author 5.0 would be a very easy way to avoid problems with inconsistency when using and reusing text.
XMetaL Author 5.0 DITA Edition costs $895.00 per user, $200 more than the non-DITA version of Author 5.0.
Pages 4 and 5 of the XMetaL datasheet provide a pretty good breakdown of the differences between the XMetaL editions (Author, Author DITA Edition, and Enterprise Edition). The difference between the DITA Edition and regular XMetaL Author is obviously the DITA support itself, which is only crucial if you or your company care a great deal about using DITA architecture for your documentation.
XMetaL Author 5.0 DITA Edition is available as a 30-day free trial at the XMetaL web site. You have to register in order to download the application.
Andrea Dickson is a technical and marketing writer based in Seattle, WA. She has seven years of experience writing for a variety of industries. She has worked with print, online, and device-based help, and enjoys the challenge of adopting new documenation technologies. She currently heads the documentation department at InfoScape Technologies in Renton, WA. Andrea graduated from Mount Holyoke College with a B.A. in Chinese Linguistics, so becoming a technical writer was sort of an accident. She SHOULD be working in import/export, according to her father. In her spare time, Andrea volunteers for STC Puget Sound, works as an ESL tutor with refugees, and enjoys photography and small, yappy dogs.