Simplifying Complexity » Training

Slouching Towards Ditaville

Eddie — Thu, 13 Aug 2009 12:52:37 +0000

Interested in learning more about the Darwin Information Typing Architecture (DITA)? I recommend that all information developers at least break the surface. Regardless of whether you plan to adopt DITA, you can benefit from studying it. You can even borrow from its lean, efficient writing model.

I have been a fan of modular, “chunked” writing since I took an Information Mapping (IM) course years ago. Although I see value in using IM, I prefer DITA’s open, simplified, XML-based model. I appreciate its emphasis on standardization and content reuse. I like the flexibility for using specialized information types. Although none of my clients have adopted DITA, I study it because I have a driven fascination with information architecture and structure.

Toe in the water or swan dive?

Most of the available information about DITA is on the web, but at least three DITA-related books have been released (as far as I know). Each of the following titles is a great resource for neophytes who find the formal specification a bit intimidating but who would like to learn more about—and possibly even experiment with—DITA.

DITA 101: Fundamentals of DITA for Authors and Managers

This 2009 release is written by Ann Rockley, Steve Manning, and Charles Cooper, three esteemed members of the Rockley Group. The book provides a straightforward introduction to DITA without becoming mired in technical details. It provides an overview of the DITA architecture, explains the benefits, and gives advice for planning a DITA implementation. It includes just enough “Advanced Stuff” (the name of the final section) to orient you toward the language of DITA. Best of all, it’s written in the same crystal clear style as Managing Enterprise Content, also a Rockley publication and one of the best books on content management.

DITA 101 is a “toe in the water” book. If you need to make a business case for DITA or compose an elevator speech, this book is your best resource.

Practical DITA

Author Julio J. Vazquez places more emphasis on the planning and execution of DITA projects. In Practical DITA, he encourages authors to start with a visual map of their information set and refer to the map throughout the information development process. He emphasizes the importance of audience and task analysis.

Of the three books discussed here, Practical DITA offers the most detailed writing advice. Vazquez introduces the basic DITA information types and explains the role of each. For example, he lists questions that a concept topic should answer. He recommends that cognitive tasks be written as concepts. He emphasizes the importance of writing “generically” and limiting related links to external content.

Practical DITA also exposes readers to the basic mechanics of DITA. The author covers such specifics as semantic naming and common semantic elements, syntax diagrams and how to create them, filtering and flagging, and linking relationships.

If you are committed to DITA adoption or simply want to develop a test project, I recommend Practical DITA as prerequisite reading. This is your “starting to dog paddle” book.

Introduction to DITA:
A User Guide to the Darwin Information Typing Architecture

Introduced in 2006 by Comtech, this book is a comprehensive tutorial. After a brief overview of the DITA architecture and the core information types, it plunges headlong into hands-on exercises. You open your XML editor and build topic examples. You work with DITA maps. You learn techniques for content reuse and specialization. You install the DITA Open Toolkit and build output.

Note: Introduction to DITA was first published three years ago, so if you buy and use the book, visit the DITA Open Toolkit site for the most up-to-date information about the current version of the Toolkit.

Introduction to DITA is your “starting to swim” book. This book is the choice for information developers who want experiential guidance in DITA content creation. You not only learn by doing, but you also become acquainted with many DITA elements. Although I recommend this book for practice, I give equal weight to Practical DITA for its sound advice.

Ready to take the plunge?

Good luck on your DITA journey! I have provided links for online DITA resources and for each of the three books discussed here. If you have additional resources or comments to share, please write.

Explore some online resources

Buy a book

Garbage 101: Acquiring Domain Knowledge

Eddie — Thu, 11 Jun 2009 15:02:25 +0000

My life as a new condo owner is currently filled with moving details and arrangements: cable installation, lock replacement, and minor upgrades and fixes resulting from our home inspection. One detail that caught me off guard and required some research was the selection, purchase, and installation of a new garbage disposal.

Let’s face it: garbage disposals are not one of those things that an average person thinks about. Unless your unit is on the wane—or as in our case, dead—you’re unlikely to wake up one morning and say “I think I’ll shop for a new garbage disposal today.” You probably won’t find yourself habitually gravitating toward the disposal display in Sears, either.

But for the past few days, I have been preoccupied with garbage disposals. My browser has been choked with an array of tabs, each displaying search results and home improvement sites. I have been reading specs, making comparisons, and learning the jargon. I learned to pay attention to specific attributes: continuous feed, sound insulation, grind chamber capacity… induction motor vs. permanent magnet motor…

One model even comes with a “self-service wrenchette … for easy clearing of jams.” My word processor doesn’t recognize wrenchette. I suppose that’s a sort of faux French word for “little wrench.”

Another model makes your life easier because

two grind stages let you quickly grind difficult food waste you wouldn’t put in a standard disposer, like celery and potato peels.

I hate when food waste is “difficult.”

Learning through research

Like most people, I start with the Web when I’m trying to tackle a new knowledge domain. Through research, I was able to narrow down my choice of product and find out where I could purchase it.

Conducting Web research reminded me that I cannot search the Web without informally evaluating the usability of sites. None of the sites that I found explained the meaning of the disposal product specs. The meaning of some terms was obvious, and I could infer the meaning of other terms such as grind capacity. But terms such as sink baffle kind of… well… baffled me. I went on a wild word chase: baffle as noun = “something that balks, checks, or deflects.”

OK, I realize that these sites simply want to sell products, but a good customer is an educated customer, right? A little embedded help can’t hurt.

Learning from experts

My research also reminded me of the discovery process that we technical communicators constantly employ whenever we start a new project. I thought of all the domain knowledge that I have acquired over the years.

At one point I oversaw a large-scale training project at the World Bank. The Bank was rolling out an ERP system, and I was responsible for developing training for the procurement module. I had never worked in procurement, and I spent many hours attending meetings—even on Saturday mornings—with procurement experts.

At the National Cancer Institute, I took on medical terminology thesaurus management. I dove deeply into papers and books on Description Logics and Knowledge Representation. I worked closely with information scientists. I developed a fascination with Tim Berners-Lee’s idea of a truly semantic Web.

Over the years, I have become immersed in many other domains, including telecom engineering, clinical care, accounting, mortgage products, law office management, and manufacturing plant flow simulation. The key to acquiring domain knowledge is to work closely with subject matter experts, or SMEs (pronounced “smeez”).

In one of my most successful projects at the United States Mint, my SME was a seasoned accounting professional. Our task was to produce a training course for the customized accounting module of another ERP system. We worked under a seemingly impossible deadline, using a collaborative strategy where my SME developed raw content for conceptual detail and exercises, and I provided additional writing, editing, organization, and overall design. We met the deadline, and our course was well received.

Projects where software developers were the appointed SMEs did not always proceed as smoothly. In most cases, software developers are in the same position as information developers. Like us, they have to acquire the domain knowledge and expertise to truly understand the needs of the users.

Users are the real SMEs. They use the products and follow the processes every day. Spend time with them. Observe them. Listen to them. Learn from them.

What’s your story?

What on-the-job knowledge have you acquired over the years? Which domains were especially challenging? I hope that you will share your stories.

Learn Flare Single Sourcing in Arlington, VA

Eddie — Sun, 10 May 2009 21:49:27 +0000

Though I teach most MadCap Flare classes online these days, I am scheduled to teach a live Flare Single Sourcing class on June 3, 2009, in Arlington, VA.

About the single sourcing class

The single sourcing class is a one-day, hands-on session that uses a scenario-based model to teach you how to single source your content with Flare. The course includes an overview of single sourcing for those who are new to the concept. It also includes advanced tips and best practices for experienced information developers.

In the course scenario, One Source Hotels is expanding to open two resort hotels: one in the US and another in Canada. The company needs to develop policies and procedures for the new hotels. They need to single source one set of content to account for differences between the customs and the legal requirements of the two countries. They need to publish to HTML and PDF.

Course prerequisites

If you are a beginning Flare user and are unfamiliar with the Flare work environment, I recommend that you take the Flare Basic/Intermediate class before attempting the single sourcing class. Unfortunately, we simply cannot cover the work environment in detail. If you have no formal Flare training but are comfortable working with the product, then you will will probably do well in the single sourcing class.

Course highlights

The single sourcing course covers many powerful Flare features, including

re-using content
maintaining a linked workflow where contributors are writing in Word and FrameMaker and publishing in Flare
creating ad hoc tables of content for different outputs
using Flare page layouts for printed output
using snippets to reuse content with embedded conditions
using variables in topics and in a TOC
running builds from the command line and automating builds with batch files
creating multiple targets (one online and one print target for each hotel)

sharing content and resources using Global Project Linking.

Details for the upcoming session

When: Wednesday, June 3, 2009, from 9 am to 5 pm
Where: 2001 Jefferson Davis Highway, Suite 610,
Arlington, VA 22202 (Crystal City, accessible by Metro)
Price: $599 per student
What to Bring: Laptop with Flare 4.2.1 installed. If you need to use a trial version, MadCap will provide a temporary key.

Questions and registration

Contact Jennifer Morse, Senior Territory Manager, MadCap Software:

Direct: +1.858.320.0387×212
Toll Free: 1.888.623.2271×212
Fax: 858.320.0338
Email: jmorse@madcapsoftware.com
Curriculum outline: http://tiny.cc/YcylK

Even if you don’t live in the Washington, DC, area but live within a reasonable travel distance, I hope that you will join us.