Just doing a little data mining of the posts I’ve written about DITA in the last few years. I think that there’s a gap for DITA users who are writers or content creators and not coders. I’d like to say that DITA bloggers can bridge that gap. Join me on the DITA blog by writing your own experiences with DITA.

These posts are ordered from newest to oldest, and I wrote them to share my experiences with DITA and to chronicle some of the Central Texas DITA User Group meetings I attended.

A watched folder for publishing from DITA source files

June 15, 2007: I’ve figured out a way to automate DITA builds where you just drop a zip file of your DITA source files into a “watched folder” and PDF and CHM files are automatically built.

Usability and inline links in user assistance systems

May 19, 2007: Examining DITA’s linking and usability.

Getting Started with DITA

April 12, 2007: A brief overview for a couple of fellow Austin writers who have asked me recently how and where to get started with DITA.

Checking out the new DITA Users website

April 10, 2007: Using a coupon code (it’s BETA) I joined the new DITA Users website for free today.

A new DITA Open ToolKit release and brand new DITA newbie blog

October 04, 2006 : A couple of blog-worthy items in the DITA world

Turning information into DITA topics

September 14, 2006: What would you do to make this particular type of content into topics?

How to substitute your custom CSS when using DITA Open Toolkit transforms

September 07, 2006 : When you want to use the DITA Open Toolkit transforms but you want to use your own CSS, here’s how to substitute your CSS for HTML Help (CHM)

DITA Open ToolKit now has a User Guide

August 22, 2006: Just released last week, the DITA Open ToolKit now has its own User Guide

Using the DITA catalog for your specializations, creating a Public ID

August 16, 2006 : Thought our discovery might help you as you specialize DITA

Evaluating XML editors for DITA

August 01, 2006: Notes from the July 2006 Central Texas DITA User Group meeting

A web-form-based DITA editor

July 14, 2006: Could this be the perfect storm for a DITA wiki?

Troubleshooting tip for the DITA Open Toolkit install

June 23, 2006 : Finally figured out the fix for my DITA Open Toolkit “resource/messages.xml” not found error

Where to put your files and other setup for DITA

June 09, 2006: Working with the environment setup for DITA

Defining OPML and relating to DITA maps

May 31, 2006: I found a nice definition for OPML from whatis.com as their word of the day, and I’m starting to wonder about similarities between OPML and DITA maps

Learning more about DITA

May 18, 2006: Learning about how to get started with DITA and a trivia item for fun

Notes from the central Texas DITA user group meeting

April 21, 2006: Two speakers shared their takeaways from DITA 2006 and CMS 2006

Our DITA experience at BMC Software

March 02, 2006: Link to a case study published about BMC’s DITA experience

DITA from the trenches

February 20, 2006: Information Architect from IBM, Kristin Thomas, presented to the Central Texas DITA User’s Group meeting last week, and here are my notes.

Moving from Books to Topic-oriented Writing

January 27, 2006 : A report from JoAnn Hackos’ talk at the Central Texas DITA Users Group meeting January 2006

DITA and wiki combo

December 05, 2005: Darwin Information Typing Architecture, meet Wiki.

Darwin Information Typing Architecture – DITA (dih tuh)

November 04, 2005: Roundup of the DITA reading I’ve been diving back in to lately.

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.

More reading

I like the Introduction to DITA: A User Guide to the Darwin Information Typing Architecture book available here.

The DITA Open Toolkit User Guide and Reference is very useful as well, and free.

Bob Doyle, an active member of the Boston DITA User’s Group, also has a helpful article in the E Content Magazine column, I Column Like I CM: Getting Started with DITA.

Use Don Day’s evaluation heuristic for editors if you want to do a full-blown evaluation for your preferences in an authoring tool.

Everyone must read Scott Abel’s article, 10 DITA Lessons Learned From the Trenches on the Content Wrangler when evaluating DITA for their doc needs.

Anyway, once you get very far with the DITA Open Toolkit you might fall back in love with the Adobe toolkit. I’d love to hear just how far you get and whether you fall in love.

Just announced last week, the DITA Open ToolKit has a version 1.3 release available now. One exciting addition for those of us who have struggled with the installation process is an all-inclusive installation package for the Open Tool Kit with everything but Java. Robert Anderson describes it in this post to the dita-users Yahoo group. I need to dig into it further, but he describes a new DITA Open Tool Kit Evaluation document that should be interesting to read. This Open Tool Kit release contains a preliminary interpretation of the DITA 1.1 specification so processing of 1.1 elements should work with this release.

I think the author of this new DITA Diary blog that I stumbled across today will be a perfect candidate for trying out the evaluation instructions. It’s neat when two discoveries on the same day seem so relevant to each other.

Here’s how I was able to substitute my own CSS (Cascading Style Sheet) file when using the DITA transforms to make compiled help files (CHM). I did several Google and Yahoo Group searches in the dita-users group for phrases like “switch css chm” and “substitute css chm” but didn’t find quite what I was looking for, so I decided to try a few things and write it up. After figuring it out, I did find the topic covered for XHTML in the DITA Open ToolKit User Guide and it contains all the information I needed to make it work for CHM. I just needed to leave that “CHM” keyword out of the search phrases I was using! Go figure.

Here’s an overview of what I did to get it to work in my environment on Windows. This process should work for other platforms as well.

First, create a CSS file that contains the modifications you want for styling your output. I basically took the generated CSS commonltr.css and made modifications to that file, then saved it as a new CSS file called bmc_dita_chm.css.

Second, make sure you can build using Ant and create your own Ant script using the ant/template_htmlhelp.xml file provided with the DITA Open Toolkit. Basically, you take the ant/template_htmlhelp.xml file and substitute your project names in the file, then save the file with a new name such as build_htmlhelp.xml. Then you go to a command prompt and type ant -f build_htmlhelp.xml. You should get output with the default CSS styling.

Next, modify your Ant build script with the following parameters: args.copycss, args.css, and args.csspath. All these parameters are documented in the Open Toolkit but I still wanted a code example that put it all together. So here it is, and you can copy and paste this into your Ant build file for HTML Help (CHM).

<property name="args.copycss" value="yes"/>

<property name="args.css"
value="${dita.dir}${file.separator}css${file.separator}
bmc_dita_chm.css"/>

<property name="args.csspath" value="css"/>

Now your CSS file will be substituted before the compile command occurs, which was like magic to me. I had originally thought I’d have to do a command-line method with quick file copies at the right times, but these Ant builds are da bomb. The more I learn about using Ant to build DITA output the more excited I am about the possibilities. Put your DTD specialization files anywhere! And then point to them using the catalog-dita_template.xml file! And then build output from anywhere! And substitute your own CSS!

Recently there has been a discussion on the dita-users Yahoo Group about styling the CSS for the Table of Contents (TOC) for the XHTML output, and there’s now a patch that enables the substitution of your own CSS for the Table of Contents. The .patch file is for use with a GNU utility called patch (Windows version is downloadable from http://unxutils.sourceforge.net/), but you can also read the .patch file to figure out which modifications to make where.

Have fun with your own customizations. Let us know if you have any other tips and tricks with customizing the DITA output.

Don Day just announced the release of the DITA Open ToolKit User Guide, which you can download from the Open Source website as a PDF or as HTML. Naturally, it was authored using DITA. My tiny contribution to some of the troubleshooting information pales in comparison to the amount of work that the team of Anna van Raaphorst and Dick Johnson did to get all the content into topics and tested thoroughly. It supports up to the most recent release of the ToolKit which is 1.2.2.

Don has a post on the dita-users Yahoo Group that talks more specifically about the efforts, other complementary documentation (like the DITA User Guide from the folks at Comtech and the version 1.0 language specification), and a call to continue to contribute and refine the content.

Great going, open source community! I expect to use the dickens out of this Guide and will contribute what I can as we continue with our DITA implementation work.

At BMC we are dusting off some DITA specializations that we did about two years ago. We were using the non-OASIS release of DITA at the time, and our XML guru discovered that where the DITA dtd, mod, and entity files once said “IBM,” they now say “OASIS.” So all of our specializations had to be changed so that the entity declarations had //OASIS// instead of //IBM//.

But even with those changes, I still couldn’t get ant to build my DITA map files. No matter what relative path I put in my topic file, pointing to the DTD, nor where I would put the topic XML files relative to the DTD directory, ant refused to find the DTDs, giving me errors like “Cannot find \dtd\tBasicConcept.dtd” or “Cannot find C:\DITA-OT1.2.2\projects\dtd\tBasicConcept.dtd.” Originally, I thought that the problem was that ant looks relative from the ant basedir directory (it’s set to C:\DITA-OT1.2.2 on my machine) instead of relative from the topic file itself. However, I learned that public identifiers are your friends and you can avoid these relative path problems via the DITA catalog file in the DITA Open Toolkit.

Using Public IDs

I didn’t actually discover this helpful method of tracking DTD references. Our XML guru and information architect discovered that we needed to have entries in the catalog-dita.xml file in order for ant to find the specializations. That addition allows us to use public IDs instead of absolute or relative paths to the DTDs in our topic XML files. Whew!

So, in my topic files, I can refer to our specialized Concept topic, “tBasicConcept.dtd” (no relative or absolute file path) and as long as the catalog-dita.xml file has these entries for the publicIds, the DITA Open Toolkit finds the DTD and builds happily.

Here are examples of the catalog entries:

<public publicId="-//BMC//DTD DITA topic BMC Basic

Concept//EN" uri="bmcproc/tBasicConcept.dtd"></public>

<public publicId="-//BMC//ELEMENTS DITA topic BMC Basic
Concept//EN" uri="bmcproc/tBasicConcept.mod"></public>

Here are examples of the referrer in the XML topic file:

<!DOCTYPE basicConcept PUBLIC "-//BMC//DTD DITA topic BMC Basic

Concept//EN"  "tBasicConcept.dtd">

Woops, the catalog can be overwritten

After a little searching on the dita-users Yahoo Group, I did find the following caveat for altering your catalog-dita.xml file directly. From Deborah Pickett in this message “Note: catalog-dita.xml is a generated file. It is overwritten when you run the “integrator” task. If you find your changes are being removed, put them in catalog-dita_template.xml instead.” I think you only run the integrator task when you are installing plug-ins, and so far we haven’t installed plug-ins in our Open Toolkit environment. So our modified catalog file is safe for now.

Separating your authoring environment from your processing environment

Now, if you were really paying attention to the catalog entries, you’d notice we’re using a “bmcproc” directory for our specializations. In our environment, we have two sets of specializations by design. One is a processing specialization, and that is the one I’m using for the ant builds. The other set of specializations is a “bmcauth” directory, and we have slightly stricter authoring standards in that set of specializations. But, we want the processing to work with the out-of-the-box transforms supplied by the Open Toolkit, so we designed more DITA-specific processing specializations.

An example of the difference between our authoring environment and the processing environment is that our BMC definition of a section is more restrictive to disallow a mixed PCDATA content model (which non-specialized DITA allows). This stricter definition prevents you from writing a section without tagged markup in our authoring environment. Where DITA allows: “#PCDATA | %basic.ph; | %basic.block; | %title; | %txt.incl;” BMC allows just: “%title;, (%basic.block; | %txt.incl;)+” and hopefully our content will be more semantically tagged because of it.

I found this DITA Tip-Where to Put Your Files the other day and it’s a nice explanation of not only how to set up the file storage for DITA topics but also an explanation of why it’s convenient and what are the advantages to this set up. I think that the hows for DITA are readily available but the whys are a little bit behind. Everyone working on DITA knows about this general lack, though, and I think the gap is being closed. I actually think bloggers can close this gap somewhat. Take a look at the DITA category for martin’s blog for an example of where he discusses real-world tips for DITA.

Environment setup

I also followed the environment variable setup found in the Open Toolkit documentation (if you install the toolkit, the Windows instructions are in DITA-OT1.2.2/doc/installguide/settingenvironmentvariables.html) and found it really valuable. It doesn’t always say why you might use Xalan, or ANT_OPS, for example, so I’m not sure whether to bother setting those up if I don’t know the intended use. I guess I can’t expect too much from what is essentially a reference topic, and not a conceptual one. But, here is what I have gathered from reading the surrounding documentation:

• Setting CLASSPATH for c:\ditaot\lib\dost.jar is optional but useful if you want to get logging information or debugging information. I believe that file was added in the DITA Open Toolkit 1.2 release timeframe. I went ahead and set it.
• If you’ll use Saxon for XSLT processing, set up an ANT_OPTS variable containing -Djavax.xml.transform.TransformerFactory=com.icl.saxon.TransformerFactoryImpl.
• Some settings conflict with others, so if you use Saxon for XSLT processing, remove all references to Xalan jars (another XSLT processor)from your classpath.

Which platforms work – plus the interdependencies

The DITA Open Toolkit 1.2.2 is tested on Java 1.4.2, Ant 1.6.5, FOP 0.20.5, and Saxon 6.5.3 releases. It ought to work with Java 1.5 but testing has shown that Java 1.5 works with Saxon but not Xalan. The whole toolkit won’t work yet with Saxon 8.x which supports XSLT 2.0. It also works with Xalan-J 2.6 but if you have Saxon jar files in your CLASSPATH, remove the Saxon jars before adding the relevant Xalan jars. In addition, to use Xalan, you’d have to ensure you’re using Java 1.4. (Yahoo dita-users group message reference) Whew! So many dependencies.

Set this, set that

One thing I’ve noticed on the dita-user group is that people will respond with, oh you need to set your this or that, but don’t always say where to set it. I found that often times people are referring to settings in the build.xml file that are properties that are defined in the doc/DITA-antscript.html file that comes with the Open Toolkit. For example, if all your topid files are .dita instead of .xml, this is the place you’d need to change to .dita in your build.xml file:
<property name=”dita.extname” value=”.xml“/>

Another observation is that oddly enough, in this case online install documentation has a huge advantage over printed because I can copy and paste URLs for downloading and environment variables to ensure accuracy. I had a tough time accurately typing \lib\avalon-framework-cvs-20020806.jar when glancing down at an open book. Plus, when I look at a printed book, I have to wonder if it’s really up-to-date, especially when versions and URLs are involved.

Troubleshooting

One great thing about this latest release of the Open Toolkit is a troubleshooting topic has been added to the help. So far there are only three common problems, and I’m having trouble with the third — Failed to load message file. However, so far, the suggested fix hasn’t worked. Still digging. I’ll keep you posted on my progress, though, in hopes of bridging that gap.

Thanks to David Brainard for figuring out the basic problem! At BMC, we all have a Documentum client installed on our desktops, so with the 4i client, my Classpath contained C:\Program Files\Documentum\Shared\dfc.jar. Apparently there is a collision of some sort between Documentum’s dfc.jar and DITA’s lib\dost.jar in the classpath which prevented the DITA Open Toolkit from running, manifesting itself as errors finding resource\messages.xml.

In my case, the fix was to remove the reference to C:\Program Files\Documentum\Shared\dfc.jar from my Classpath environment variable. Since this discovery, I’ve upgraded to Documentum 5 client, and there is no longer a collision. The Documentum 5 client inserted “C:\Program Files\Documentum\dctm.jar” in my classpath, but the DITA Open Toolkit doesn’t seem to mind that.

Apparently other applications can be “classpath hogs” so to speak, so if you get a “can’t find resource\messages.xml” error message, remove other items from your Classpath variable one-by-one until you find the culprit. In my case, we created a simple “run.bat” file that contained only:

set CLASSPATH=C:\saxon\saxon.jar;C:\ant\apache-ant-1.6.5;\lib\dost.jar;.

ant demo.faq

Couple of notes about this batch file – the dot at the end is for your current directory. We chose to do ant demo.faq rather than ant all because it won’t take as long if the build is successful. An “ant all” build can take anywhere from 2-13 minutes.

By setting the classpath just for this session and running this batch file within the DITA-OT-1.2.2 directory, we could pinpoint that it was my Classpath that was the issue, and then remove entries one by one. It’s a handy troubleshooting tip. Thanks again Dave!

Jen Linton, the co-author of Introduction to DITA:Getting Started with the Darwin Information Typing Architecture is in Austin to teach the DITA Getting Started workshop hosted by BMC Software. I’m attending along with several of my co-workers, and we’re all learning a lot.

Last night I went to dinner with Don Day, chair of the OASIS DITA Technical Committee, Jen, and Wendy Shepperd, a manager here at BMC. Jen asked Don, “What’s the story with the bird in the DITA logo?” I had blogged earlier that it’s a finch with a specialized beak, but it turns out there’s more to the story. Don explained that it’s a woodpecker finch, one of the finches Darwin documented from the Galapagos Islands, and it’s a tool-using animal. Woodpecker finches pluck the spines from cacti or use wooden splinters to extract grubs and other bugs from holes that their beaks don’t fit for a tasty meal. That’s a fun piece of trivia. Here’s the logo to which I’m referring.

After dinner we went to the Central Texas DITA User Group meeting, where Jen told and showed us how she assembled the Introduction to DITA book using DITA topics. The most interesting part for me was to learn about the Mekon FrameMaker plug-in that lets you import DITA content into FrameMaker for book assembly and above all, index generation. Nifty! It’s part of the DITA Open Toolkit if you browse the CVS repository.

In our training class, we wondered out loud where all the local User Groups are forming currently, and I found this list at http://dita.xml.org/user-groups:

Canada

• Ontario: Toronto DITA User Group
• British Columbia: Vancouver DITA User Group

United States

• California: Silicon Valley DITA Interest Group
• Indiana: Indy DITA
• Massachusetts: Boston DITA User Group
• New York: NY Metro DITA Users Group
• North Carolina: Research Triangle Park DUG
• Texas: Central Texas DITA Users Group (Austin)