TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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
www.geoff-hart.com
--------------------------------------------------
Coming soon: _Effective onscreen editing_ (http://www.geoff-hart.com/
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. http://www.DocToHelp.com/TechwrlList
Now shipping: Help & 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 & Manual: http://www.helpandmanual.com
