Musings on structured, topic-oriented authoring

18 Feb

Posted by Scott as DITA, XML, authoring, documentation, markup, writing

Anne Gentle posted a very interesting piece on DITA. Part opinion, part analysis, part musing this post is definitely a must read.

This post got my, yet again, thinking not just about DITA but about one of the concepts that underlies DITA: structured, topic-oriented authoring.

Going back in time

I first started seriously thinking about structured, topic-oriented authoring in 1999. After a 2:00 a.m. feeding shortly after the birth of my daughter that year, I wrote the basis of a whitepaper/report/whatever you want to call it on the subject of using XML to create documentation.

One passage in that document sticks in my mind to this day:

XML can change the way in which you work with documentation. And not only in the way the documentation is created and managed. By moving to XML, there will be a fundamental shift in the way you view documentation. You will move from seeing manuals and Help files as documents with a beginning, a middle, and an end (perhaps a holdover from the English/Arts backgrounds of many writers), to seeing documentation as structured components of information. You can then take these components and fit them together as needed, as if they were blocks of Lego.

Learning to build with the Lego

The first part of the title of Anne’s post is an interesting question: “Can DITA train writers?” I still believe what I wrote in 1999 is true: DITA will force technical communicators to change the way that they perceive and create content. We’ll have to toss out the idea of a rigid narrative flow, and adopt a more compartmentalized way of writing and viewing documentation. The narrative flow will still be there, but it will be much more fluid. That narrative will develop based on context. More or less the Lego approach that I described.

Getting there won’t be easy. It’ll take a lot of training, a lot of trial, and quite a bit of error. But for certain types of documents, the effort will be worthwhile.

On top of that, you’re focusing on content and not appearance. That’s not a new concept; it’s one of the underlying principles of the TeX and LaTeX typesetting schemes. You just have to worry about writing, and let your XSLT and formatting engine(s) do the rest of the work.

Is structured authoring right for everyone?

I’m still not convinced that structured authoring is the best solution for all documentation, or for all documents. As I wrote (in the context of DITA), structured authoring is a good fit for organizations with large documentation sets, which have a lot of content reuse, and which generate with complex documents having multiple output formats.

I’ve worked with smaller firms, which have had one or two products, for which a structured, topic-based authoring method wasn’t the right fit. There wasn’t enough reuse of content — which was handled ably by FrameMaker’s text inset feature — and breaking the documents down into discrete chunks would have been a lot of work for minimal returns. To both the authors and the audience.

In the conclusion of her blog post, Anne makes a great point:

Heed the warnings and experiences of others before making the leap to topic-oriented single-sourcing or your expectations and those of your customers may not be met.

Structured, topic-oriented authoring is a useful part of any technical communicator’s tool kit. The time will come when you will need to use that tool, and you’ll be glad it’s there. That said, you shouldn’t jump on the structured, topic-oriented authoring bandwagon simply because it’s the latest thing. You really must take the time to analyze your needs and the needs of your customers to determine if this approach is right for your documentation.