Formatting Doesn't Matter

Tools like Word and FrameMaker, InDesign...they're great. You can tweak and twiddle with the formatting to your heart's content. You can make the content look just like you want it to, down to the smallest little thing.

But here's the rub: It doesn't matter a damn. The reason you are creating this content is to communicate with others. The people you are trying to communicate with don't give a damn about all the tweaking and twiddling that you've done. They simply want something that's clear and simple to understand. So you spend a very high proportion of your content time fiddling with formatting - for no good reason whatsoever.

Before you come chasing after me and telling me I'm wrong, I know that what I've just said doesn't apply to marketing and advertising material. If you are going to put an ad in a colour magazine, then yes you should tweak it to within an inch of its life.

That kind of content however only accounts for a very small proportion of the content that companies create. By far the largest proportion of the content is what could generally be called "technical documentation". My contention is that formatting - beyond the most basic - only matters to one person: That person is you. It doesn't matter to the consumers of that content. The consumers of that content don't care about all the time that you spend tweaking that content. They only care that the content is clear and simple to understand.

I heard an alarming statistic recently: A company had a documentation process where the engineers wrote the documents in Word and then the writers came along and edited it and tweaked it until it looked right. How long do you think it took to create each page of documentation? Eight hours! Eight long hours.

That company changed to a process where the engineers input the content into an XML editor and then the writers edited it for sense. The content was output to publication through a standardised process. The new documentation approach took 1 hour per page of content.

That is a huge difference. It is a huge saving for any company, particularly when companies report that documentation costs around 6% of revenue.

I think there is a lifecycle with writers. At some point in their career they become obsessed with presentation. They love the tools that deliver that presentation to them. Whole departments become obsessed with presentation, and indeed whole companies can become equally obsessed with the "company look and feel". Fine if you are delivering a web site. Forget it for the rest.

Later writers and companies move beyond the attraction of presentation and begin to realise that most of their content is functional content. Functional content is just that: content with a function. If it fulfils that function and does it well, then that's what you are after.

That's why companies move to DITA, S1000D and other similar standards. Because they realise that they cannot afford to be fulfilling the fantasies of their staff who are obsessed with presentation. Presentation without relative benefit.

That doesn't mean that you cannot deliver presentation using XML standards. It does mean that the design and codification of presentation is a Write Once and Once Only process, just like with content preparation. Then you just run it when you need it.

The worst possible situation is to move to one of the XML documentation approaches and to try and drag your presentation fetishes with you. Then you really are taking it too far!

So for all those people who cannot free themselves from the tyranny of presentation my message is to Just Do It. I promise you'll feel better.

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.

DITA - Reduce, Re-Use, Recycle

In any business you will typically have a set of documents that use common content. This always causes problems. What tends to happen is that content is copied and pasted into multiple documents and as it changes and as the number of documents multiply it becomes harder and harder to keep it up to date.

The nice idea would be to keep that content in a database and only update it at the source and then use it wherever you need it. That's been the holy grail for years, and if you were a large company then you probably had the money and the expertise to do that. The ASX, for instance, had a system like that for some of their publications back in the early 90s. Good but highly technical and very expensive.

Enter DITA. DITA is the Darwin Information Typing Architecture - go and Google it for some background. In short DITA uses XML format documents to create topics - short chunks of information - and uses ditamaps to combine those topics into publications. But there's a whole lot more there than that.

DITA can be output in a number of formats - do you want to use your XML topics to generate a website? DITA can do that. Do you want to use the same content to create a PDF document? DITA can do that. Eclipse Help? Use DITA.

You can use open source tools to run your whole DITA solution - there is a thing called the DITA Open Toolkit that does all the processing and you can use "free" XML editors to create content.

That's OK until you want to have content available over the web or to collaborate on content. Then you need a more complex solution.

That's where XDocs comes in. It is a content management system designed for DITA. It stores content, manages links and generates content output. It's a Java application, runs in Tomcat and uses MySQL as the database. So there's plenty of open source kit in the background.

XDocs runs on Windows, Linux and I just did the first Mac OS X install on Snow Leopard over the last few days.

Why do I use it? Imagine a Pilot Operating Handbook for your favourite aircraft and imagine the downwind checklist. Now imagine the POH for another similar aircraft and the downwind checklist. They're likely to be the same. Why would you write them 2, 3, 4 or more times to keep versions of POHs up to date. In our case the aircraft manufacturer "owns" the content and we manage the publications. Trying to keep multiple POHs up to date using MS Word or something similar is just not possible. Not if you want to stay sane.

Instead we have a library of topics which range from the procedure used to do a weight and balance (the same for all aircraft types) to the CG limits for the aircraft (different for each type). We generate them at runtime into the POH for the appropriate aircraft type. XDocs allow us to utilise publishing profiles so that we can exclude content which meets certain criteria. This allows us to put content into a map but to exclude some of that content for a particular aircraft type. Each aircraft gets a hard copy POH, a CD and we also serve the same content up on a Knowledge Base website that is part of the XDocs product. Very sweet and smooth. If we change content in just one place it changes for each of the uses that it is put to.

XDocs has a number of parts. The server runs in Tomcat and uses MySQL to store content. There is a Java client application that again runs on the three platforms. It allows you to access and manage your content repository, which by the way can also include other types of documents, images or other digital assets. Then there is the editor that is called from the client application. In our case we use XMLMind but you could also use XMetal - XDocs has integrations for either.

In addition there is a content management portal that is accessible via a web browser that allows you to access the repository and to generate content - if you want to build a PDF on the fly at a customer site then the portal allows you to do that. Finally there's the Knowledge Base which allows you to serve a map as a website.

But here's the punchline: XDocs, which is developed and sold by Bluestream, is cost effective for small business and yet scalable for growth. As well it's simple to configure and manage. This is a great product.

So whilst we may not be as big or complex as Airbus Industrie we are using similar technology to manage our documentation. In their case the same content chunks are used for printed publications, EFBs...you name it the content is re-used for it.

If you are interested in DITA and its background then simply hit Google, you'll be surprised how much is out there. If you want to chase down the theoretical background then search for John Carroll and minimalism, you get to stuff like this. It is very relevant to aviation documentation and learning.