Getting from here to there

This is the story of a typical software documentation shop. We use unstructured Frame and WebWorks.  We deliver PDF and CHM. We deliver in several languages. We deliver customized documents for different markets. We barely have enough time and people as it is -- and there are new products, languages, and markets on the way.

Before we drown, we have a little time to read furiously about all the new and wonderful solutions out there: Enterprise content management. Information design. XML. Topic-based authoring,  DITA. But these solutions require a significant investment. We need a plan. We need a business case. We need a project manager and a budget.

Meanwhile we're busy writing and publishing software documentation, on a product schedule some might characterize as unreasonable, if not insane.

How can we do it?  Do we plan for years in our spare time, and then one day spring our solution fully formed  like Athena from the head of Zeus? Probably not. The reality is that  we are going to have to get there one small step at a time.

So we've started. We're already several hesitant steps along. In this weblog, I'll try to record the journey.

Topic-based authoring is old, say going back to Ed Weiss' "How to Write a Usable User Manual" and STOP back in the 60's. But, if you knew how to do that, English majors would cringe and not hire you.

Coverting to non-linear, topic-based authoring should have been the norm back in WinHelp, but of course, single sourcing back then meant ignoring media specific drivers of information architecture.

Apparently, the hardest thing about DITA isn't teaching English majors how to write it. It's getting the junk to run. The consultant can't do it. The vendor can't do it. So it will be deadopted by our shop. I think the savings gained in reduced translation expense is more than made up by vendor and consulting costs. As I remember it, my last DITA shop had two production people whose job it was to make the junk work.

I came late to the implementation here. Be absolutely sure to write up the requirements including the things you think should work like page numbers on TOCs, and indexes, cross references, conditional text, figures that are not enlarged or shrunk, and the page layout you want. And, the bigger time wasters like an application that can't keep the graphics filepath and the xml file filepaths separate, or the labels in the editor that should show up in text, but don't. Then, run an acceptance test against all the vendors. The software they install for training isn't what you'll install in production. Your production install won't work. Don't go fast. They want to sell you stuff beyond DITA. Skip them. Take your time. It will take you a year to get the junk to work.

Topic-based authoring is easy. Getting output is hard.

David Locke

Thanks for that advice. You sound a little jaded, but at least we can learn from your experiences. Through Frame-DITA I'm getting output, but it's still far from automatic, and there are still a lot of important things I have to try out.

It's interesting that you say single-sourcing "back then" meant ignoring media-specific drivers of information architecture. To a significant extent, that's still what it means. Technologies like DITA theoretically afford the luxury of developing different architectures for different outputs, but there is still a  temptation, and arguably a practical necessity,  to design for one medium and let the others catch as catch can -- witness the discussion of "all that glue" on this site.

Thanks again for the excellent vendor requirement suggestions. As for getting output, I remain optimistic, but also reasonable -- I've peered into the technology, and I fully expect this to take a year or more. Focus Areas: BPEL | DITA | ebXML | IDtrust | OpenDocument | SAML | UBL | UDDI
OASIS sites: OASIS | Cover Pages | | AMQP | CGM Open | eGov | Emergency | IDtrust | LegalXML | Open CSA | OSLC | WS-I