Darwin Information Typing Architecture (DITA): An Afternoon With JoAnn Hackos

By Lance-Robert, President

On Thursday, February 16, I had the great privilege of watching Dr. JoAnn Hackos present "Moving from Books to Topics: A DITA-based Approach" to the STC San Gabriel Valley Chapter in Monrovia, CA.

Before the meeting, STC San Gabriel Valley President Vanessa Flint had extended a special offer for members of the Inland Empire, Orange County, and San Diego chapters to attend at their regular member rate of $25.

I was very fortunate to catch a ride to the presentation with Walter Hanig and Alison Butler, who were the only other members from the San Diego chapter to attend. Jeff Randolph and Kerry Tani, my Orange County and Los Angeles chapter counterparts, respectively, were also among the many in attendance.

Dr. Hackos prefaced her discussion of moving from books to topic-oriented writing by announcing that books are here to stay, and that manuals, while they might look like them, are not actually books. Product users get only the information they need from manuals and typically do not read them from beginning to end. She reminded us that product users are not readers, and that they need quick access to information to:

Perform tasks.
Meet their goals.
Get their work done.
Go home by 5 PM.

The customers require:

Task-oriented information for getting things done.
Current, up-to-date information.
Minimalism: Less information = No glut.
Information that is easier to use and to find.

Traditional desktop publishing (DTP):

Preserved book structures (chapters, sections, and subsections).
Provided format with function.
Provided markups that are too generic for technical manuals.

In organizing our topics, we need to know what information the user is looking for, and we need to be a lot more flexible with that information, so that it can be retrieved using a variety of different methods. Our users think of our content as data, rather than words, and we as authors need to do the same.

A DITA-based approach helps us to cater more to individual needs and provides a better means for us to "paint pictures with our content."

The topics in a topic-based architecture are:

Discrete units of information covering a specific subject, with specific content.
Small enough to promote reuse across multiple contexts and output media.
Large enough to be easily authored, readable, and coherent.
Organizable units using a wide variety of structure, from linear to networked.

This figure shows the DITA topic model, which consists of three primary information types: concept, task, and reference.

Topics enable users to perform essential tasks or reach certain goals.
Concepts support knowledge so that users can perform those tasks successfully.
Reference provides additional information.

DITA is authoring in topics that conform to a hierarchical architecture. These topics are mapped to provide print, Web, and online help outputs.

We need to establish a relationship between our topics so that we can reuse them in these multiple contexts.

This figure shows the information relationships.

DITA promotes repurposing, so we don't need to use other tools for other outputs.

To enable this reuse, our topics must conform to standards, be usable in many contexts, and provide conditions for:

Job roles
Product types
Workflows
Solutions

When planning our topics:

Begin with tasks that users must perform to reach a goal.
Consider possible scenarios that show typical user tasks in the context of real world goals.
Turn basic tasks into introductory tutorials.

It's important to define our topics firsts and to get any needed SMEs onboard with this implementation. We must be consistent with our presentations.

Remember that topics enable variable elements.

The reference information consists of:

Text
Tables
Figures

Manuals are tools that must be filtered to use.

Some benefits of a topics-based approach include:

Topics make manuals economically possible.
Topics help to promote a minimalist agenda, so there are fewer words to manage.
Topics promote structured and consistent writing.
Topics are easier to localize, reducing costs.
Topics provide a means for multiple deliverables to meet the needs of diverse user communities.

A typical XML tag for a task would look like this:

<tasktitle>How to Turn on the Power</tasktitle>

We need to have a style standard. For example, Dr. Hackos recommended that we begin all tasks files with the words "How to..."

We also need to have an authoring standard, and ensure that all tasks correspond to user goals, not system functionalities.

We need to know what kind of content is:

Required
Recommended
Consistent

To learn more about DITA and topics-based authoring, Dr. Hackos recommended these conferences:

Content Management Strategies Conference
April 3-5, 2006
San Francisco

Best Practices Conference
September 18-20, 2006
Paradise Point Resort
San Diego

In conjunction with the Best Practices Conference, Dr. Hackos has offered to make a presentation to the STC San Diego chapter on Thursday, September 21. For more information, click here:

www.stc-sd.org

More information is also available online:

As for vendors, Dr. Hackos said that Blast Radius is currently shipping XMetaL Author DITA Edition (4.6), an editor that supports DITA mapping. More information and a free 30-day trial of the software are available here:
http://www.xmetal.com/en_us/products/xmetal_author_dita/index.x

As a side note, Justsystems announced their intention on March 7, 2006 to acquire XMetaL from Blast Radius. The company has pledged to maintain the different versions of the product and to continue their development and support.

Dr. Hackos left us with these pointers:

The hardest part of moving to topics-based documentation is coming up with your information design.
DITA tools are good now, but they will only get better with time.
The next version of ArborText Epic (E3) will support DITA mapping.
When we write our topics, we need to think of them in a context.
Cascading Style Sheets (CSS) can work with DITA for HTML output.
The current DITA version is 1.0. DITA version 1.1 is expected to be available in mid-2006, and DITA version 1.2 is expected to be available by the end of the year. More information about this can be found here:
http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=dita

My thanks again to Walter Hanig for the long ride to and from Monrovia and to Vanessa Flint for letting us attend at their regular member rate.