Re. Documentation types -- what are the possibilities?

["Geoff Hart" <geoff-h -at- mtl -dot- feric -dot- ca>]

Bobbie Dofflemyer is in the process of <<...developing a 
documentation strategy for a suite of products... What types of 
documentation/media do you use to present information and how 
do you choose the most appropriate method?>>

We use the standard mix of online and print documentation; if 
resources permitted, we might add online tutorials or interactive 
wizards, but that's not in the cards anytime soon. (We develop 
software as a secondary goal, not our primary raison d'etre.) So I 
start with the philosophy that users should have the basics they 
need to get started with a product in print (i.e., an overview of how 
things work, the metaphor used in the application, a brief tutorial, a 
glossary of key terms), and put the primarily context-sensitive 
reference material online. I'd prefer to work more closely with the 
users of the product to find out what they want, but that's rarely 
possible; instead, I get feedback from the guys who actually deliver 
the product to customers and work with the customers. See if you 
can do a better job of talking to your audience than I do!

<<If I have a complex product that I need to document -- one that 
involves a specific methodology and some fairly elaborate 
processes in addition to the interface-driven procedures -- where do 
I put the different types of information?>>

Sounds to me like the users really need a comprehensive overview 
that explains what all the components are and how they fit 
together. Using this as your starting point, you can provide high-
level information on which component they should start with for 
certain tasks, and how (and when and why) to move from that 
component to another to accomplish typical tasks. The details of 
the tasks can be set in their own chapters or even their own 
manuals if the application is sufficiently complex. Better yet, you 
can turn them into "user support" materials and integrate them in 
the interface, either directly (as affordances) or indirectly (as 
context-sensitive help).

<<Do I provide some sort of tutorial or demo that illustrates the 
processes?>>

Tutorials are very helpful, particularly if you can put them online so 
they show what happens rather than describing it; that frees up the 
user to sit back and watch what's going on, and "learn by doing" 
rather than bouncing back and forth between a printed tutorial and 
whatever's happening onscreen. But tutorials of that sort aren't 
necessarily easy to write well; you may need a bit of training, and 
some quality time with the users to find out what works for them.

<<Do I ditch the user's manual altogether (managment's 
suggestion for less printed documentation) and develop an online 
document that can provide the same information?>>

Nope. I'm still the voice in the wilderness who considers "online 
help" to be an oxymoron. Until both the tools and the writers skills 
improve, putting docs online is primarily a way to save printing 
costs and transfer them to your customers.

<<what do you consider to be a good mix of documentation?>>

Doesn't much matter what _I_ consider to be a good mix. What do 
your customers consider to be a good mix? If you can't ask them 
directly to find out, start by sitting yourself down in front of the 
computer, playing dumb ("I'm not really a tech writer who knows 
this software from top to bottom"), and asking yourself: "What do I 
do now?" The answer gives you a decent idea of what to do: it may 
be "I want an overview so I know where to start" or "I want a wizard 
that walks me through this process" or something else entirely.

<<Also, how do you meet the mandate for more online 
documentation when you truly feel that the information is best  
presented in hard copy?>>

"Kobyashi Maru"! (That is, you cheat. <g>) Anything you can put    
on paper, you can also put online. So you move most of the 
context-sensitive stuff online, where it's most useful, and add in the 
high-level overviews you've provided on paper, and voila: you've met 
the mandate for more online docs. But you've also kept the 
important high-level stuff on paper for those who need printed 
information.  

--Geoff Hart @8^{)}  geoff-h -at- mtl -dot- feric -dot- ca  (Pointe-Claire, Quebec)
"If you can't explain it to an 8-year-old, you don't understand it"--Albert Einstein