AODC Day 3: Introduction to DITA Conditional Publishing
A couple of weeks ago I attended AODC 2010, the Australasian Online Documentation and Content conference. We were in Darwin, in Australia’s “Top End”. This post is my summary of one of the sessions at the conference and is derived from my notes taken during the presentation. All the credit goes to Dave Gash, the presenter. Any mistakes or omissions are my own.
This year’s AODC included a number of useful sessions on DITA, the Darwin Information Typing Architecture. I’ve already written about Tony Self’s session, an update on DITA features and tools, and about Suchi Govindarajan’s session, an introduction to DITA.
Now Dave Gash presented one of the more advanced DITA sessions, titled “Introduction to DITA Conditional Publishing”.
At the beginning of his talk, Dave made an announcement. He has presented in countries all over the world, many times, and he has never ever ever before done a presentation in shorts!
Introducing the session
To kick off, Dave answered the question, “Why do we care about conditional processing?” One of the tenets of DITA is re-use. You may have hundreds or even thousands of topics. In any single documentation set, you probably don’t want to publish every piece of the documentation every time.
Conditional processing is a way to determine which content is published at any one time.
Dave’s talk covered these subjects:
- A review of DITA topics, maps and publishing flow
- The use of metadata
- The mechanics of conditional processing
- Some examples
Metadata and the build process
Dave ran us through a quick review of the DITA build process and the concept of metadata. Metadata has many uses. Dave talked specifically about metadata for the control of content publication.
Metadata via attributes
There are a number of attributes available on most DITA elements. These are some of the attributes Dave discussed:
- audience – a group of intended readers
- product – the product name
- platform – the target platform
- rev – product version number
- otherprops – you can use this for other properties
Using metadata for conditional processing
Basically, you use the metadata to filter the content. For example, let’s assume you are writing the installation guide for a software application. You may store all the instructions for Linux, Windows and Mac OS in one file. When publishing, you can filter the operating systems and produce separate output for each OS.
In general, you can put metadata in these 3 locations (layers):
- maps – metadata on the <map> element. You might use metadata at this layer to build a manual from similar topics for specific versions of a product.
- topics – metadata to select an entire topic. You might use metadata at this layer to build a documentation set for review by a specific person.
- elements – metadata on individual XML elements inside a topic. You might use this metadata to select steps that are relevant for beginners, as opposed to intermediate or advanced users.
Dave gave us some guidelines on how to decide which of the above layers to use under given circumstances.
Defining the build conditions to control the filtering
Use the ditaval file to define the filter conditions. This file contains the conditions that we want to match on, and actions to take when they’re matched. The build file contains a reference to the ditaval file, making sure it drives the build.
Dave talked us through the <prop> element in the ditaval file, and its attributes:
- att – attribute to be processed
- val – value to be matched
- action – action to take when match is found
A hint: You can use the same attribute in different layers (map, topic and element). Also, you don’t need to specify the location. The build will find the attributes, based on the <prop> element in the ditaval file.
Next we looked at the “include” and “exclude” actions. Remember, the action is one of the attributes in the <prop> element, as described above. Here’s an example of an action:
<prop att="audience" val="novice" action="exclude" />
Dave’s recommendation, very strongly put🙂 is:
Don’t use “include”. Stick to “exclude”.
The basic rule is: Everything not explicitly excluded is included.
Dave’s final recommendation
Go get DITA and play with it!
It was great to have a focus on the conditional publishing side of DITA. It’s something I haven’t had a chance to get into before. Now I know the basics, which rounds off the DITA picture for me. Thank you Dave for an entertaining and information-packed talk.