Magical manuals, take II

[geoff-h -at- MTL -dot- FERIC -dot- CA]

 Michael Wing responded to my comments that incorporating
 some details in the form of schemata is useful:

 <<I agree that it's not an either/or situation.  The car
 example is a "one action, one effect" situation.  But what
 about a choice of actions, parameter values, and multiple
 possible effects?>>

 In that case, the schema becomes analogous to that of the
 new driver sitting in the driver's seat for the first time:
 "Welcome to your new car. You can do several things from
 your current position: start the car, steer the car,
 control your speed and power, listen to the radio, and
 adjust the environmental controls." Page numbers or similar
 references follow. [This is a quickie attempt at a
 solution, so please pardon jargon and any omissions... I'm
 illustrating, not producing a final example.]

 <<For example, a GUI is presented that allows the user to
 display geographic data based on a projection.  Through the
 GUI, the user selects a projection algorithm, sets azimuth,
 lat/long origins, horizontal data centers, and so forth.
 As a result, the software displays the geographic data
 based on the projection the user defined... If I were to
 tell them, select an algorithm, set the parameter values,
 and press OK, the software produces a projected map.
 However, the results may not be what they expected.>>

 Try this (again, a first draft): "The map you're gonna get
 depends on a combination of the algorithm, the... etc.
 Here's how the software decides the result..." In effect,
 you're explaining enough of the program logic so that the
 user can predict what is going to happen. Usually, this is
 a good candidate for a table based on parameters across the
 top, and outputs down the side. The table takes the form of
 "to get this (output), use the following combinations
 (parameters)". A flowchart or decision tree might be more
 effective. On the assumption that the program logic is
 indeed predictable, it's a relatively simple exercise in
 information design to produce such a graphic. (Even if the
 logic is stochastic, you should still be able to come up
 with an explanation of the logic that works for the user.)

 Most importantly, for a _user_ manual, you should define
 your structure based on what the user wants to achieve
 (i.e., "to get this type of map, do the following");
 working the other way around, by speccing the parameters
 first, works better in a reference manual. The actual
 implementation will be more complex than that in reality,
 but that's how I'd attack the problem, revising details as
 necessary to fit the reality of the interface.

 --Geoff Hart     @8^{)}     geoff-h -at- mtl -dot- feric -dot- ca
 Disclaimer: Speaking for myself, not FERIC.