Build-to-Order Documents with DITA

It is entirely possible to deliver custom, on-demand documentation that is precisely suited to a user's needs. It can be done today, using web-interface strategies and the right document format. This post shows how such a system could be implemented with the DITA format, and shows why it would be an ideal document-delivery system for programmers.

After learning some 20 programming languages, and an equal number of scripting languages, I can tell you that the one path to success I have found is to find a program I really want to write (hopefully, one that is suited to that language), and then figure out how to write it.

If I decide the program needs to X, Y, and Z, I start by learning how to do X. Then I figure out how to do Y, and so on. At the end of the process, I'll have a useful program, and I'll have learned some subset of the programming language skills needed to be proficient in that language. That gives me a basis to learn more--when I have another program I need to write.

Some people apparently have the ability to sit down and work through a tutorial from start to finish. I'm glad about that, because I love writing tutorials for them. And I know that I would learn a lot, if I could discipline myself enough to it. But I must confess to a short attention span. I learn as much as I need to know to finish what I'm working on, then I'm on to something else.

A system that does that can be built with DITA.

"Build to Order" with DITA 

DITA provides a complete set of tools to implement a solution--and DITA is available today.

My personal use case is centered around programming languages. If there is a collection of topics that explain how to do things, I'd like to select the ones that pertain to aspects of the problem I'm trying to solve. The system would manage dependencies among topics, showing me a suggested TOC that orders the topics and adds fundamental prerequisites I need to know. I could then de-select topics that I already understand.

At the end of that process, I would have a book that shows me how to use a programming language to build the kind of application I have in mind. I could then use each example in the book as a guide, building my program as I work though them. Later, when I want to add functionality, I would create a new book that contains only the new things I need to know.

Such a system would deliver "agile documentation" appropriate for an agile development project. It would tell you the exact set of things you need to know for the next version of the program you're building. The keys to the implementation are sequencing and dependency management. With DITA, those problems could be solved with:

  1. A master map that determines sequencing for all topics.
  2. One or more dependency maps.

The master map list all topics in the order they would occur in a book. (Ideally, the master map would be constructed from the dependency maps, but it wouldn't have to be for an initial implementation.) Each item in the list would then be presented to the user along with 3 radio buttons: Skip, Include if Needed, Include. The default, pre-checked in each case, would be "include if a prerequisite".

An advanced implementation could keep a list of topics the user claims mastery in, and pre-set those topics to "Skip". Such an implementation might also have an option to hide skipped topics, to simplify the view. (They would only be needed when suggesting a book for someone else. In which case it would be desirable for the user to be able to select one of several standard profiles that match different certification standards, and then modify/save that profile for future use.) Similarly, the advanced implementation could disable the "Include if Needed" option for leaf node topics--topics that are not prerequisites for any other topics.

Such advanced features provide convenience, but they aren't strictly necessary. For an initial implementation, the full sequence could be delivered to the user each time. That just leaves the implementation of the dependency maps.

There are two ways to make such maps:

  1. Multiple small maps, each of which leads to a leaf node--a topic that is not a prerequisite for anything else.
  2. A single map that establishes a dependency network.

Multiple small maps are the easiest and most natural to construct. The sequence would go from most basic to most advanced, in the same order that you would present them in a book. Each map in that implementation would look like a "thread" in the Java tutorial--but instead of having a single "Swing thread", there might be one thread that culminates in a Swing Table, another that culminates in a Swing Tree, etc.

Although natural to write, the disadvantage of that system is the amount of redundancy. For example, the sequence, "Create a class", "Create an Inner Class", "Handle Swing Events", might occur in the thread for every high level Swing component.

That redundancy can be eliminated by reversing the map sequence so it goes from most advanced to most basic. Doing that provides two additional advantages:

  1. Topic nesting can be used to organize the dependencies--so only one dependency map is needed.
  2. Since maps can reference other maps, a full network of dependencies can be modeled.

A map that models a dependency network might look something like this:

  • Topic: Swing JTable Component
    • Topic: Writing a Table Model
    • Map: Swing Event Handling
    • Map: Swing Basics
  • Topic: Swing JTree Component
    • Topic: Writing a Tree Model
    • Map: Swing Event Handling
    • Map: Swing Basics

In that high level map, the map for Swing Event Handling is reused to eliminate redundancy. That map would look something like this:

  • Topic: Handle Swing Events
    • Topic: Create an Inner Class
      • Topic: Create a class

Since these topics have a sequential relationship, they're nested. (In the previous map, there a parallel relationship was implied. It didn't really matter if "Writing a Tree Model" came before or after "Swing Event Handling", so the references were listed in parallel, rather than nested. The order given was the suggested order, but not a necessary order.)

It is easy to imagine further modularity, of course. For example, there could be a topic for handling AWT events that would also depend on Create an Inner Class and Create a Class, so those two topics could be factored out into yet another sub-map.

To create the sequence map, the system would traverse the dependency network, reversing the sequence of the topics it finds, ignoring duplicates along the way. Since DITA already provides XML structures for the maps, topic references, and sub-map references, the problem devolves to the following sequence of activities:

  1. Parse the dependency map(s)
  2. Build the sequence list
  3. Create a UI to present the user with choices
  4. Generate a specialized map from the user's selections
  5. Optionally, provide a way to save the specialized maps and/or the user's set of skipped topics
  6. Process the specialized map to construct tailored output

So there is certainly a fair amount of work to be done. But it is noteworthy, I think, that DITA provides all of the basic mechanisms required to implement such a system, and it provides them today.

Next: Build-to-Order Docs--Today! 

Additional Information


We are doing a built to order DITA for semiconductor addressible register maps (ie memory-mapped registers). One example DITA register map is at

Posted by Jeremy Ralph on September 26, 2007 at 11:07 AM PDT #

Post a Comment:
  • HTML Syntax: NOT allowed

« July 2016