Re: Any ideas for a presentation on the documentation process?

["Anthony Markatos" <tonymar -at- hotmail -dot- com>]

Krista Van Laan asks:

I and a writer in my group are going to give a presentation on the
documentation process to the engineers ...... Has anyone had any luck doing 
the same thing or any ideas on how to make it interesting?

Tony Markatos responds:

I have done this many-a-time.  The best way is to draw parallels between 
what (software) engineers do and what technical writers do.  There are a 
lot!  A couple of examples:

1.)  Software engineers perform a Systems Analysis.  Tech Writers perform a 
Task Analysis.  These are really the same thing: specifying noun/verb 
combinations that state what the system does.  While, Engineers call these 
combinations "functions" and Tech Writers call them "Tasks", the differences 
are just cultural.  "Calculate Sales Tax", "Staple Form X to Form Y", 
"Determine Time Available", and "Visit Grandma" (providing that doing such 
is within the scope of the system under consideration) can be called either 
tasks or functions.  No difference.

2.) Good design for both software and end user manuals is characterized by 
minimum interface complexity between parts of the whole.  Good software 
design has a minimum number of "go-to's" between modules.  Good 
documentation design has a minimum number of "skips" (skip over material to 
get what you really need) and "jump-to's" (jump from one section to another 
to find what you need).

3.)  Standardization of terminology is just as important in an end user 
manual as it is in a logical data dictionary.

I can go on-and-on, but you get the picture.

Tony Markatos
(tonymar -at- hotmail -dot- com)






______________________________________________________
Get Your Private, Free Email at http://www.hotmail.com