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!

AODC Day 3: Introduction to DITA Conditional Publishing

AODC Day 3: Introduction to DITA Conditional Publishing

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

Example:

<step audience="advanced">

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!

My conclusion

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.

Update on DITA Features, Tools and Best Practices

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 25 May 2010, in AODC, technical writing, xml and tagged , , , , . Bookmark the permalink. 4 Comments.

  1. ?? Can’t say I’ve ever thought of using that conditionalization before.. 🙂

    You can also use ditavals to flag content, that is, insert a nifty icon like [Linux] next to your Linux instructions.

  2. I’ve used conditional text in Framemaker for years, usually for regional markup and print vs. online markup. But this isn’t really DITA (even though structured FM supports it). Or, at least, it’s always been my assumption that’s its not DITA, because I don’t use XML or structured Framemaker. (I really just haven’t spent the time to try an learn it as the unstructured version of FM handles everything I need).

    I have conditional tags for EMEA, LATAM, APAC, US, and Canada. Plus I have Print_Combined, Print_StandAlone and Print_Targeted as well as Comments. My online help generator takes all these into account as well (obeying the FM instructions as I have specified in each project).

    I think DITA goes beyond this and adds quite a bit more, as you’ve noted, for a lot of other properties. This isn’t really applicable to most of what I do since docs for other platforms typically require an entirely new document (the content for our Linux installs, for example, is completely different than the content for Windows installs). It’s still something I’d like to learn more about, though. I think it would make content management easier and more reusable.

  3. Thank you Carrie and writerdood, for adding the extra tips on conditional processing. It’s not something I use in my day job either at the moment, so it’s really interesting to hear titbits about it, first from Dave and now from you too.

  4. @writerdood, The flagging is especially helpful when you have parallel commands for different operating systems, like:

    [Linux] mycommand.sh …
    [Windows] mycommand.bat…

    With the DITA tagging, you then have the option of either flagging these paragraphs with different icons in the same document, or generating a Linux-only or Windows-only document (by using excludes).

    However I agree that sometimes you have to write a whole separate document for different operating systems/platforms. Depends on the content.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: