How do you create "Choose Your Own Adventure" docs?


#1

Imagine you have a product which can be installed on several operating systems, and has several component parts, some of which are optional extras.

In that situation, how do you, or would you, document the installation process? I have experimented with Google Forms, presenting each decision point with associated text and building the installation guide that way. That experiment was “inspired by” the GitHub Pages documentation.

I am keen to hear from others about how they tackle this situation.


#2

I am a fan of tight introductions in my docs, and if I have two sections that are very similar (i.e. commonly confused with each other), I will cross-reference the other section in the intro. My intros are short and great for wayfinding. I make it super easy for the reader to figure out whether they are in the right place.

Example:
“Follow these instructions to create and install your own certificates, if required. These instructions use xxxx. For xxxx, refer to section 4.5 instead.”

Note that “if required” is how I flag optional content.

You might be able to use this idea to write and design your docs.

Lastly, an If-then table might help you provide several options all at once.


#3

I think the key thing to remember here is that any given reader is only interested in how to install one particular configuration. They are not interested in learning about all the other systems it could be installed on.

The other important factor is whether the reader has to make any decisions about which pieces to install or where to install them. In other words, is there a planning process that has to take place before the actual installation process takes place. If there is, it is a distinct process and should be documented as such. In the planning process, the reader does need to know all the options available and the questions they have to answer to decide which ones to install.

Once those decisions are made, they want a simple straightforward install procedure for just the options they have chosen.

The decision points are part of the planning documentation, not part of the install documentation. For installation, you want a separate install procedure for each of the possible outcomes of the planning process. (Depending on the number of options involved, this may need to be generated dynamically.

Each procedure should clearly identify which decision path it belongs to and direct the use back to the planning topic if they are not sure they are in the right place.


#4

When I read this question, I thought of Khan Academy where you do indeed go down a self-designed path.

For installation procedures, I most often use the following structure if the content is lean enough:

On Linux, … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … .
On Mac OS X, … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … .

On Windows, … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … . … … … … … .


#5

@RussellDickenson Can you post a small screenshot of what this looks like verbatim?


#6

I am a big fan of conditionalized text using DocBook and oXygenXML. Curious about leaner options to do the same, however.


#7

I’ve been working on an enterprise software product with exactly this setup for about 10 years. Because the product is so specialized, the customer base is pretty small. They also still want install information in PDF format. As a result, we author in DITA (using Arbortext Editor) and use conditional processing to create an install guide for each platform.

If we were able to provide the install information online, I’d like to think that we’d present options at the end of each section not as Related links, but as What do you want to do next? then have a list like:

  • Install the product on Linux
  • Install the product on Windows
  • Install the product on AIX
  • Install optional features