ThunderBird: A Sample DITA Documentation Set to Play With

Here’s something I think needs to be more widely known: sample DITA files mimicking a professional manual set for a fictitious product called Thunderbird. I’ve been using this example code for a couple of years now in demos and for presentations, and there’s at least one person in every audience I show this to who was not previously aware of its existence. If you are looking for some sample DITA files to learn from and to play with, this is a great place to start.

The project was originally sponsored by the consulting firm Gnostyx Research and included contributions from Joe Golner, Jacquie Samuels, and several other people. Its goal was to provide a set of sample DITA file designed to demonstrate the capabilities and benefits of DITA using an example documentation project that could be expected in the real-world. This portion of the demo content focuses on core DITA 1.2 features, and the files work as a good example as to how a set of end-user manuals for a software product can be created using DITA.

Some time later, along comes Eliot Kimber who clearly realized the potential of these demo files to spread practical information on how to implement DITA 1.2 keys and tease about how DITA 1.3 key scopes could be implemented. In all, there are three separate, but equally valid, sets of example DITA files to play with.

Getting the Files
Downloading the sample DITA files is easy, but may appear daunting for anyone who is unfamiliar with Github.
First thing is to head to the Github page for the demo files: https://github.com/gnostyx/dita-demo-content-collection. Look for the green “Clone or download” button on the right-hand side of the webpage. Click on the button.

A dropdown will appear. What you want are the files, so click on the Download ZIP link. Depending on what you have configured for dealing with ZIP files, your program of choice should appear.

Simply drag these files to wherever you want on your local hard drive, and voila! you have the Thunderbird DITA demo files on your system.

So What Files Do We Have?
As previously mentioned, there are three separate sets of DITA files. They are:

• Thunderbird: the original documentation set rendered using DITA 1.2
• Thunderbird-keys-reuse-only: this version uses keys for all topic references so that there exactly one URI reference for each topic.
  Resource-only keys are also defined for all images used in this documentation set along with all topics used two or more times within the different maps in the information set.
• Thunderbird-keys-resonly-every-topic: this version declares a resource-only key for every topic and image, so all navigation topicrefs utilize keys. Consider this version to be “keys to the max”.

To get a sense of the differences between the three versions, here’s an except of the same section of XML from the User Manual from each version respectively:

They each do the same thing—point to a particular set of topics—but do so via different means. This is one of the great though often confusing aspects about DITA: it often provides the user with more than one way of doing the same thing. What these files help demonstrate are how flexible keys can be and how they can be effectively deployed. Its up to the technical writer (or more properly, the Information Architect) to determine which use of keys (if any) are optimal for their documentation team.

A couple of other things worth looking for in these DITA demo files:

• How everything is supposed to work from a DITA perspective is explained in the master_control.ditamap document. Start here.
• All of the images used are contained and referenced within two “image warehouses” files; look for r_image_warehouse.dita and r_image_warehouse_2.dita in each version, and note how the images are reference directly in the original version, and indirectly via keys in the two key-based versions.
• The publication-set.ditamap files in the key-based versions include info on how it could be used in a DITA 1.3 environment using key scopes.

Changes for the Future?
While these files are great to have for people in the DITA community to learn from and play with, I am kind of hoping that someone will spend the time necessary to update these to DITA 1.3. The great thing about Github is that this is entirely possible, and someone could fork an existing branch of one of these documentation sets and proceed to load it up with DITA 1.3 goodies. Here are my suggestions as to what to include:

• Adding some proper key scopes code to the existing files
• There are at least two t_troubleshooting_* task files that are begging to become proper troubleshooting topics
• Sprinkle in a few elements from the XML Mention domain, such as for the tags that appear in the email template within the c_notification_templates.dita file
• Add some fictitious changes to the prolog of selected topics using the Change Management domain to demonstrate how it can be used in practice to generate a change log
• Accessibility markup for the various tables throughout the document set.

There are probably a few more DITA 1.3-specific things that could be done to help make this a showcase for aspect of the latest standard, but these would make for a good start. Since this is an open source project, adding a new version with these features is something that the DITA community can certainly do.

In the meantime, now that you know about these demo files, try them out!