Getting Started with DITA

A brief overview for a couple of fellow Austin writers who have asked me recently how and where to get started with DITA

I have gotten two similar questions about getting started with DITA in the time span of about two weeks, so I thought I’d borrow from some of my answers as a write-up for a blog post. One person wants to ditch her Adobe toolset in frustration and try out some DITA workflows with all free tools. The other is a lone writer in a small shop and wants to find out more about DITA and see if it might work well in her Agile development environment. While I’m a huge DITA advocate and see many ways that DITA can help with many doc goals, I don’t think that DITA has all the answers necessarily. Topic-based authoring with just concept, task, and reference types is a different mind set for both writing and publishing. But, you could certainly put together a toolkit of freebies with DITA to try it on for size. So here are some starting points.

Get very familiar with topic-oriented writing

Without some up-front information architecture and design where you really analyze your documentation needs, and figure out what task, concept, and reference means for your body of work, DITA won’t help you. Transforming legacy information into topics may or may not be a worthwhile effort so some up front analysis will help you.

Bare minimum tool set to “do” DITA

You’ll need the DITA Open Toolkit, available at http://sourceforge.net/project/showfiles.php?group_id=132728. Here are direct links for the 1.3 package that you just download and unpackage on your hard drive. Windows zip Linux tarball

These full packages of the DITA Open Toolkit contain all the sub-tools that you need for full evaluation from authoring to building output. Most of these tools require the Java Platform, so, Java is a prerequisite to using the DITA Open Toolkit. Download and install the Java Platform Standard Edition (SE) 5.0, available at http://java.sun.com/j2se/index.jsp.

Ant 1.6.5 runs automatic builds on your DITA maps, and the DITA Open Toolkit gives you ant scripts for builds already.
Xalan-J 2.6 is an XSLT processor which is required to run the transforms.
FOP 0.20.5 is needed for PDF output. (Note: For compiled HTML help (CHM) you’ll need the HTML Help Workshop, which isn’t included in the Open toolkit, but most help authors will already have this installed.)
ICU4J 3.3.4 is included for improved NLS-enabled index sorting.
Apache Catalog Resolver 1.1 is a standard XML catalog mechanism.

Plus, the newest full package (1.3) contains a startcmd batch file in the root folder that you can use to set up your environment each time you run the DITA Open Toolkit. Considering what headaches I had just with environment variables in Windows, I am greatly appreciative of this little batch file.

If you want to first just look at topics and create some output before authoring anything of your own, look at the EvaluateOT.html file in the root directory of your DITA Open Toolkit install. Double-click the startcmd.bat file, then type ant samples.web -f build_demo.xml at the command line and you will have your first set of DITA output in a newly-created \out folder in your DITA Open Toolkit installation folder.

When you want to create your own topics and maps, you’ll need an XML editor. While you can certainly edit DITA XML in Notepad, you’re going to want a validating XML editor for serious authoring and evaluation. See my suggestions next.

DITA XML Editors

Previously I posted my notes from Don Day’s talk at the Central Texas DITA User’s Group about evaluating DITA editors: http://talk.bmc.com/blogs/blog-gentle/anne-gentle/dita-editor-eval. Now, the next step for me is to start naming names. Let me be clear, though, since I’ve been on maternity leave for the last six months or so, I haven’t been seriously evaluating XML editors for BMC. Others are doing that and I’ll be happy to use whatever they recommend for our environment. But, for my friends who have been asking me about DITA, let’s break this evaluation into free and not-so-free. Note: nearly all enterprise-level XML editors have 30-day trials, but it’s tough to get enough done in a 30-day evaluation of DITA and the XML editor if you’re just starting out with topics and DITA.

Awareness of DITA is not always an easy achievement, apparently, and when you’re new to DITA, it’s tough to evaluate “DITA aware.” So I guess you just need to trust others when they say an editor is a DITA aware editor.

Free XML editors

XML Copy Editor – this open source project has an XML editor that claims to support DITA. https://sourceforge.net/projects/xml-copy-editor/

DITA Storm – this is a free web-based DITA editor. You can either install it yourself if you have a web server, or try out the ditausers.org online web-based editor for free (use the coupon code BETA) during the evaluation period.

Enterprise-level XML editors (with 30-day free trials)

I believe that you should convince your manager you need this level of editor if you’re serious about writing DITA topics for end-user doc.

Bob Doyle has done an excellent job of evaluating XML editors in this article, X Marks the Spot: Let’s Take Today’s XML Content-Creation Tools for a Spin, complete with tables of prices, platforms, support info, all the specs you’d need to evaluate a tool for your environment. The ones I have installed and tried are: Adobe FrameMaker ($799), Arbortext Editor ($695), XMetaL Author DITA Edition ($895), and Syntext Serna ($195). You would have to determine what’s right for your particular environment and preferences.

What to do to start writing DITA topics

Open your XML editor and start with either a concept, task, or reference topic type. Or even start with a topic to begin with. Write some content, and validate it as you go. Once you get a handful of topics, make a DITA map either using the code in an XML editor or using a DITA Map editor like the Task Modeler available as an Eclipse plug-in.

What to do to get output from your DITA topics

You can modify the ant scripts provided with the DITA Open Toolkit for your own builds. I was able to do a few ant scripts just based on the template files and examples the toolkit provides. I used the “ant/ sample_htmlhelp.xml” template to make this build file for my map file named processfile.ditamap on Windows. Edited: to link to the sample build file code instead of posting it here because apparently our DIV layout doesn’t like wide-width PRE areas in the middle column. 🙂

Nice-to-have tools for anything beyond just evaluation

You’ll want to automate building output with Ant. The example build file above gives you a start, and there are plenty of templates provided in the Toolkit.

Once you think about enterprise publishing, reusing topics across groups, and so on, you’ll want to use a Content Management System. I think CMS tools for DITA is an entirely different topic that deserves more research so I won’t say more than that yet. To get started on larger doc sets without a CMS, use a logical folder structure and defined file naming conventions, then use the OS search tools to look for metadata within topics.

A DITA map editor that either integrates with the CMS or the free Task Modeler from IBM has a really good visual method for editing DITA maps.