Decision Guide Specialization

Figuring out which components you need and accessing the documents that describe them is a big issue for any reasonably complex system. Providing an end-user with the ability to do that is a huge part of “usability” in documentation. One of DITA’s most important advantages is the ability to define specialized document structures. That capability can be used to define a Decision Guide document type.

Originally prepared in 2008

The need to decide which things to do, and the best sequence in which to do them, is the hallmark of any reasonably complex endeavor, from creating a WordPress site to establishing a Java development environment. 

On any measure of complexity, putting together a Java environment you need is right up there with the best of them. (I’m going to focus on the Java environment here, merely for illustration. The problem is even more acute in most of the Apache documentation I’ve read and, indeed, in most every complex software system I’ve ever seen.)

You Don’t Know What You Need to Know

For one, thing, you have to know stuff:

• If you want to run stuff, you get the JRE, if you want to build stuff, you get a JDK.
• Most developers use the “Java SE” JDK. Enterprise developers need “Java EE”.
• The JDK includes a JRE, which lets you run stuff. But you’ll also need a vanilla JRE, to replicate the end-user’s environment.
• The “deployment” process doesn’t apply to server apps.
• “Plugin” development is really “applet development”
• The right sequence of installation and operation is… ?

You Spin Your Wheels Looking for Stuff

But then, in order to figure out what you need and the order you need them, you need to access documents that are nowhere near adjacent to one another:

• java/jre/…/guides
• java/j2se/…/guides
• java/…/guides
• java/…/java_webstart/…/guides

The lack of adjacency has you taking a “drunken walk” through the documentation space, gradually building up a picture of how things work. 

Using a Specialized “Decision Guide” Structure

Right now DITA has multiple specialized topic types that are generally focused on the question of “how to do it”:

• Concept topics that explain the fundamental things you need to know to do something.
• Procedure topics (aka Tasks) that show you, step-by-step, how to do it.
• Reference topics that give you the detailed information you need to create variations on the basic procedure.

What DITA generally lacks, however is a specialized topic type that focuses on determining what you need to do (evaluating your choices), and when (doing those things in the best sequence).

To make it easier to decide, here some guidelines that could be incorporated into a specialized topic type:

• When the user has a choice, make sure you tell them how to choose.
  (This principle is one of often overlooked in technical documentation, which is perhaps the number one reason why most documentation runs so low on the usability scale.)
• The best how-to info the world won’t tell you what doesn’t work.
  (The further you have to go before finding the blockage, the deeper the dead end. Knowing what won’t work is what keeps consultants in business — because running down a dead end at high speed invariable ends with a headache.)
• Eliminate dead ends with a decision guide.
• To do that, use a specialized version of a “Reference” topic to display a comparison table. 
  (In that table, every entry for option B that has a blank cell next to for option A tells you that option A won’t work for that purpose. It’s a way of saying “Option A doesn’t do that”, without having to be negative about it.)

Please share!