The Content Wrangler asked technical writing guru Mark Lewis of HyperWriters, Inc. to talk about his experience moving into the world of the Darwin Information Typing Architecture (DITA).

TCW: Mark, tell us a little about yourself.

ML: Before my current position I worked at a bleeding edge software company that was really gung ho on XML technologies. So much so, that we for our upcoming SDK we embedded the descriptions of all programming objects directly into the XML that became the code. Our problem then became, getting the descriptions back out and into a usable Help format.

My specialty is writing context sensitive Help for Windows applications, so I’ve played in Doc-To-Help and RoboHelp a lot. I used to be a software engineer where I wrote Windows programs using a object-oriented design methodology. That was all about writing programming objects for reuse. So when I found out about content reuse for tech writing, I was hooked.

Currently I am captured at a software company that develops an XML editor that is a Word plug-in, Xpress Author I was hired to write the next generation of Help for this application. I’ll be using our XML editor to produce that Help.

TCW: Why did you decide to adopt DITA?

ML: DITA appeared to provide the publishing answer that I was missing at my previous job. We knew enough to know that having our content in XML was cool. But, we couldn’t figure out how to publish without custom programming.

Before we adopted, I tested DITA to see if was a good fit for us by structuring the existing Users Manual in Microsoft Word. I was please with how I made the manual more consistent overall, just from that exercise. I was already convinced as to the benefits of reuse, so we pushed ahead.

TCW: What documentation (content) did you use DITA to create?

ML: I hope to, for example, write our software feature descriptions once and reuse them in the Users Manual, Training Guides, Release Notes, Software Requirements, White Papers, Marketing web pages, etc. We plan to use DITA to create most of our documentation.

TCW: Is any of this content available (can I point to it) on the web?

ML: We have not yet posted any of the documents described above on our website, but will in the near future.

TCW: How many writers were tasked with creating content using DITA? And, were the writers geographically dispersed?

ML: 2 writers, 1 location.

TCW: What content management tools did you use to help you manage the content and the writers tasked with creating DITA content?

ML: No CMS tool yet, but we are planning to.

TCW: What authoring tools did you use to implement DITA (did you use FrameMaker, XMetaL, etc.)? If so, what versions? And why?

ML: We are using our own DITA XML Editor for Word plug-in, Xpress Author. We wanted to eat our own dog food and prove the usability of the product.

TCW: Why didn’t you just use Microsoft Word to create DITA content?

ML: Poor support for XML. Too easy to shoot yourself in the foot and create invalid XML documents.

TCW: What benefits did DITA provide you over the old way of creating content?

ML: Moving to structured authoring helped us make our documentation more consistent.

We haven’t got this far yet, but I hope to reduce my workload by reusing what I’ve already written over and over. And not having to maintain many versions of the same thing. I hope to my Release Notes and White Papers will mostly become a drag ‘n drop effort.

TCW: What “lessons learned” can you share with others interested in considering a move to DITA?

ML: See if DITA is right for you by practicing using it in plain old Microsoft Word first. Mark content chunks that will become topics as concepts or tasks. Start structuring your content into those topic types. If it “flows”, if the structuring process feels good and is not painful, then DITA could be right for you.

TCW: There’s a lot of hoopla surrounding DITA. It’s been over-hyped as the cure-all for many content problems. Can you think of any content types that would not lend themselves to DITA and why?

ML: RFP’s come to mind. They seem to come in some many different flavors that don’t seem topic-oriented.

TCW: Did writers have any difficulties or issues using DITA? If so, what were some of the common ones?

ML: Probably the most pain felt was when we had to structure a document that was linear and not topic-oriented. Just breaking the content into chunks did not let those chunks stand on their own two feet. They were part of a flow and so the content had to be converted to standalone independent content. This is of course not specific to DITA, but it is related and was some of our pain.

TCW: Is it possible to move to DITA and really mess things up?

ML: If you have multiple writers (technical and/or SME) and do not have a reuse strategy in place, you can mess yourselves up and defeat the whole purpose of reuse.

TCW: If you had a DITA wish list, what functionality would you add to DITA and why?

ML: Maps have so many different uses, that I think a query tool for generating all different kinds of maps would be helpful.