IBM Rational interactive install guide

Because many IBM applications can be used on a large number of supported platforms (for example, operating systems, application servers, and databases), the install guides often include a lot of information that users will never need to see: someone using Windows would not care about any instructions that are specific to Linux.

So when a coworker asked if we could create a customized install guide for every operating system, I started tinkering and came up with this.

Challenges

  • Organize dozens of tasks to fit hundreds of possible scenarios
  • Create a new tool that allows people to create an install guide that contains only information that is relevant to them
  • Present complicated technical material as clearly as possible
  • Create the tool with only HTML, CSS, and Javascript

Tools

  • Coda
  • TextMate
  • Dojo

Too long; didn't read

Basically, I turned a pile of topics that looked like this:

Original task hierarchy for installing the Rational Asset Manager server application
click to embiggen
Original table of contents for the product

…into this:

Form that asks people how they're installing the software
click to embiggen
Simple questions

…which gives you this:

Results page seen after submitting the form
click to embiggen
Easy-to-follow answers

“Can we get an install guide for Rational Asset Manager tailored for every operating system and application server?”

The above question from one of our sales representatives seemed simple enough, until I did some math: you can install one of 2 editions of Rational Asset Manager on one of 4 operating systems running one of 4 application servers with one of 4 database applications. There are even more choices on top of that, so when you multiply it out there are over five hundred combinations of software you can use.

(OK, to be fair, some combinations are impossible, so if we rule those out you're still around 300 or so. Much better. Right.)

For a small team, creating hundreds of install guides to cover every possibility isn't a reasonable option.

Breaking it all into tasks

We generally don't write information tailored to specific applications if we can avoid it. Instead, we write tasks that cover chunks of activity and that match how people think about what they're doing when they need help (For example, I am trying to set up the database.). For Rational Asset Manager, those tasks could range in complexity from "Download the files" to "Deploying the applications to your server."

By thinking and writing in tasks, you can break the installation into roughly 40 actions that cover every combination of software; each of the hundreds of possible install paths uses some combination of a few of those tasks. That's manageable, right?

The problem with tasks

Although I can easily maintain 40-odd tasks, every combination of supported software has variations in the the number and order of tasks that you have to complete. Here are some examples from the product I work on, Rational Asset Manager:

  • There's a tool that can deploy the applications to the server for you, unless you're using a Tomcat server
  • You have to create a database, unless you're using both WebSphere and DB2, in which case you can skip that
  • You will usually configure security settings in the middle of installing the product, unless you're using Tomcat and LDAP, in which case it must absolutely be the last thing that you do or else you will be locked out of the product.

Oh, and the only way you can organize those tasks in the help system is with a chapter-subchapter-subsubchapter hierarchy.

So, although someone might only need to do a few tasks, you need to fill it with all sorts of prerequisites, postrequisites, caveats, and if-this-then-that statements. It's not easy to keep it all straight.

When you have to write a sentence like "If you are using a Tomcat server and you have already installed Rational Team Concert and you want to configure it to work with Rational Asset Manager, then go do this," you're asking a lot of your busy customers, who have to mentally unpack that logic to connect the dots through the install guide.

So, I started to wonder, "What if I could connect the dots for them?"

Letting people build their own install guide

I set out to make a user-friendly tool that would:

  1. Ask all of the questions that might affect your install;
  2. Then show them only the tasks that they would care about and put them in the proper order.

The prep work

Although it wasn't fun, I had to figure out, for lack of a better word, the puzzles:

  • Depending on your choices of supported software, which tasks actually matter?
  • And which tasks now can be ignored?
  • Do you always do tasks in the same order, or can the order change?
  • Can any tasks be grouped together?

After I was able to answer all these questions logically, I was able to answer them programmatically. Enter HTML and Javascript.

Asking the right questions

The form looks like this:

Form that asks people how they're installing the software
click to embiggen
Simple questions

All right, it's just a form. It's not very complicated; in fact, I think that's its best feature.

There are, however, some nice extras. The form dynamically disables combinations that are not possible (for example, we do not allow you to install the standard edition of the product on a clustered application server). There are also little pop-up tooltips that provide more information about the more complicated options.

Tooltips for form inputs
click to embiggen
Tooltips with extra information

Providing the applicable chunks of information

After you submit the form, it goes away and you see a list of all the appropriate tasks you need to follow to install the product.

Again, despite the complicated logic that is necessary, the user only sees a simple list of topics.

Results page seen after submitting the form
click to embiggen
Easy-to-follow answers

In an early design, I provided only links to the appropriate topics, but now the page loads the complete text of those topics. If you want to print out a complete install guide customized for you, a quick File > Print and you're all set.

Content of linked topics loaded into the page
click to embiggen
Loading the full content of linked topics into the page

All told, that sales representative that wanted a handful of custom install guides is pretty happy, and our customers have been thrilled to have a clear guide for navigating our complicated installations.

Am I doing it wrong?

Comments? I don’t do open comments. Life is too short.

If you have something to say, get in touch via .(JavaScript must be enabled to view this email address) or on Twitter.