June 26, 2008 STC DITA

STClogo copy.jpgames-andrea-copy.jpggoering-tom-copy.jpggrey-joanne-2-copy.jpginkster-carolyn-copy.jpgmorgan-martha-copy.jpg

On Thursday June 26, 2008 at the Network Meeting Center in Santa Clara, the STC Silicon Valley Chapter held a panel on DITA. Andrea Ames of IBM moderated a panel consisting of Fair-Isaac’s Tom Goering, MaxiScales’s Joanne Grey, IBM’s Carolyn Inkster and NetApp’s Martha Morgan. They shared their experiences in planning, preparing and implementing DITA projects as a huge undertaking or as a single-handed effort. Text from DJCline.com.

Andrea Ames has worked with DITA teams for at least five years at IBM. She gave an overview and introduced the panel.

Darwin Information Typing Architecture (DITA) is an Extended Markup Language (XML) Document Type Definition (DTD) describing file elements and their semantic relationships or interaction to each other such as headings, paragraphs, or steps. The four topics for DITA are Task, Concept, Reference, and Generic. These topics can be extended or specialized. Text from DJCline.com.

DITA works well if your large documentation library has lots of redundancy. If you have an installation manual for four different products that are ninety-five percent similar and constantly need updating, you may have a case. If you have large libraries of static or legacy documents it may not pay for itself. It is hard to get away from the concept of book versus topic models using maps. An architectural tree of document maps is drawn up. Maps are a list of pointers to your topics. You can have a build map, a review map, navigation tree or table of contents for online help depending on your deliverable output. Changing deliverables doesn’t create the cross-reference or linking problems of Frame. One change is propagated across the structure and referenced accordingly. Editors can focus mainly on new content and less on revisions as they are automated. Text from DJCline.com.

Tom Goering is just starting to implement DITA at Fair-Isaacs, the company that gives you your FICO score. He helped put together the business case, training and implementation for DITA. The business case was easy because they reused common components in multiple applications with localization. He picked a reasonable budget number and found other parts of the company that share a common need for that reuse. He found his users, their tasks, defined the topics and started building. Chunks are translated just once and built into a localized publication saving as much as $50,000 on one project. There can be a dividing line between old and new documents as you use DITA moving forward.

Joanne Grey started using DITA four months ago as a lone writer at MaxiScales and already has DITA up and running. She bought a book and a copy of xMetal for about $700 and got to work. She loves Frame but saw a move away from book-based documentation and looked at DITA for automation and flexibility. It is a huge leg-up if you think in a non-linear fashion. She writes it once and it goes away, saving time for learning about the product. Your writing becomes crisper as subject matter experts focus of content instead of style. Read once, approve once and publish many.

Carolyn Inkster worked from the beginning of DITA at IBM over five years ago and now helps customize it for various situations. Key factors for DITA specialization were cost avoidance and timesavings for trouble shooting and customer service. When a topic needs localization, she tells the translators where the IDs are and it is done. DITA allows writers to focus on content and not style. Don’t worry about whether something is bold or italic or the size of a table. Experts like to review relevant small topics rather than large tomes, but have that option if they really want it. One source she recommends is Anna van Raaphorst and Richard (Dick) Johnson’s User’s Guide for the DITA Open Toolkit available on Source Forge.

Martha Morgan of NetApp is an experienced information architect who implemented DITA over two years ago. There has to be a pain point where you decide that DITA makes sense. DITA would not work with large installation posters where there is not much overlap between products. DITA would work if an application writer has to write a conceptual topic that might already exists in the library. People skills are as important as technical skills. It requires a much more collaborative way of working together. The silos come crashing down as you become a producer and consumer of content. Content writers meet with style people to discuss their needs. The documentation architecture can start at a high level and be refined as you get down to the nitty-gritty.

As for the future, IBM is working on faceted browsing or being able to essentially create DITA on the fly for the web.

After reading this I realize I need to use DITA to organize all the topics discussed in this article.

06-26-08-stc-dita-panel-copy.jpg

Copyright 2008 DJ Cline All rights reserved.