Documenting interactive configuration - HELP!

Subject: Documenting interactive configuration - HELP!
From: Geoff Hart <ghart -at- videotron -dot- ca>
To: TECHWR-L <techwr-l -at- lists -dot- techwr-l -dot- com>, Peter Neilson <neilson -at- windstream -dot- net>
Date: Wed, 21 Feb 2007 13:06:56 -0500

Peter Neilson reports: <<I'm documenting the configuration of dozens of different kinds of software that are used on the company's computers. Most of the them use some sort of configuration script or XML or whatever. To document the configuration I can include the file or refer to it, or include a portion of it, possibly with explanations. One program, however, is configured interactively. The configuration seems to consist of whatever the tech typed into the config screens as they went past his eyes. I tried writing up a precis of the answers that differed from the default, and it's horribly confusing.>>

Seems to me that there are two overall themes in this particular documentation problem. First, there's the overall sequence of events, which should be consistent for all configurations -- that is, I assume that the sequence of steps (e.g., choose a server) is fixed, even if the options aren't. If it's wholly random, then the developers should be able to explain what randomization technique they used so you can describe that. <g> Second, there's the series of options at each step within the overall sequence.

This suggests that one solution is as follows: First, list the series of steps in the configuration as main headings, and follow each main heading with a short summary of what the user will be trying to accomplish in that step. Second, list the options available at each step and why the user might want to choose one option over another. For bonus points, you could provide an alphabetical listing of all the options as a "look up" table.

-- Geoff Hart
ghart -at- videotron -dot- ca / geoffhart -at- mac -dot- com
Coming soon: _Effective onscreen editing_ ( home/onscreen-book.htm)


Create HTML or Microsoft Word content and convert to Help file formats or printed documentation. Features include single source authoring, team authoring,
Web-based technology, and PDF output.

Now shipping: Help &amp; Manual 4 with RoboHelp(r) import! New editor,
full Unicode support. Create help files, web-based help and PDF in up
to 106 languages with Help &amp; Manual:

You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot-
To unsubscribe send a blank email to techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit

To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit for more resources and info.

Documenting interactive configuration - HELP!: From: neilson

Previous by Author: Any comments on Word 2007? (Take II)
Next by Author: What did you learn when you competed in the STC competition?
Previous by Thread: Re: Documenting interactive configuration - HELP!
Next by Thread: Re: Documenting interactive configuration - HELP!

What this post helpful? Share it with friends and colleagues:

Sponsored Ads