Thursday, November 5, 2009

The Zen of DITA

Why Zen? Because part of the key to success with DITA is letting go, freeing yourself. Most of us these days are "children of the word processor". We are used to formatting our documents as we create them. Formatting is an integral part of our document production process. What's more, many of us don't even use the style sheets and other tools which help us to control our formatting.
That's OK when you're writing a letter or a short document. Quickly however as version management becomes an issue - both from document changes and to support purpose variation - the process of keeping control of the document gets right out of hand. Then as documents get larger and more people have a hand in those documents the situation becomes worse. Finally, usually just at deadline time, we run up against some formatting foible and sit there cursing. Often as not our version management lets us down and the wrong version sees the light of day.
This is just the point where the three disciplines of DITA become important:
  • Separate content creation from content presentation;
  • Be minimalist in creation of content;
  • Follow the DTD;
It's similar to why some of us like using a text editor for writing - some of us even use vi. The mere fact that there are no presentational tools available means that we are free to concentrate on what we are writing, to the exclusion of all else. We don't have to worry about format - that problem comes somewhere else in the production chain. With DITA presentation is linked to purpose and purpose is provided for at run time - at the point we produce a publication, a set of HTML files, a PDF, a Word doc or whatever else.
That's another part of the separation. Not only is the presentation layer separated from creation layer, it's also abstracted from the user. It can't be casually tweaked at run time. It relies on whatever parameters have been set in the processing tool. This means that no longer are we able to or required to worry about presentation at run time. Those decisions have already been made and implemented.
This is of course anathema to some organisations and some people. They have become so used to, indeed so addicted to tweaking and fine tuning that they are both unable and unwilling to move beyond that process. For those who are able to free themselves DITA provides outstanding utility.
When Frame released conditional text it was a boon for many of us. Now for the first time it was practical to re-purpose a document, a single document, for multiple uses. It proved, however, to be clumsy to implement and manage. DITA takes a giant leap forward. Maps and conditional processing again allow the ultimate in content re-use and re-purposing. Key to this is the granularity of the content. Monolithic Word documents gave way to FrameMaker books and these in turn have given way to DITA topics. Cut and paste between monolithic documents is not a practical re-use strategy. Indeed it's simply courting disaster. You will stuff up and it isn't sustainable.
By adopting a minimalist approach to content we achieve two important outcomes: First we have to think about what we are writing and how it will be used. Topics become well tuned informational and instructional gems. Secondly we are purposing that granular content for re-use. By its very nature the level of granularity we achieve in constructing topics makes those topics ideal for re-purposing.
When we came to analyse whether DITA could be used for aviation documentation our first step was an analysis of what we needed and what we had. It quickly became apparent that DITA was absolutely ideal. Checklists fit naturally into tasks and whole documents simply chunked themselves into sensible topics. In fact it was surprising to see a whole complex Pilot Operating Handbook turn itself into a pile of topics - with very little heavy lifting on our part. Perhaps only one topic in the whole POH extended to more than a page. Most were significantly less. Issues of difference between aircraft types resolved themselves with conditional processing. Indeed there's far more the same between types than there is different.
The DTD, Schema, call it what you like, can seem like a straight jacket. You wrestle with an editor which simply won't allow you to mess with the structure of the document. It can seem like an unbearable straight jacket, constraining your every move. Or it can feel like an incredible weight off y our shoulders. We no longer have to concern ourselves with presentation and now we don't have to worry about the flow of the topic - the DTD mandates what comes next. For us the initial concern was whether the names of the elements would match our needs. It was a non-concern. Where they don't exactly match there is always a sensible mapping. So the DTD becomes a part of our freedom. It means we have one less set of decisions to make.
So that brings us full circle. DITA is capable of managing the most complex document structures and enabling the most complex publishing missions. It achieves this by dealing at a level of remarkable simplicity, by being highly granular and by ensuring that each chunk of information is simple and manageable. So simplicity and zen-like freedom in fact delivers a highly capable document production system.

No comments:

Post a Comment