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

Subject: Re: Any ideas for a presentation on the documentation process?
From: "Anthony Markatos" <tonymar -at- hotmail -dot- com>
To: KVanlaan -at- verisign -dot- com, techwr-l -at- lists -dot- raycomm -dot- com
Date: Sat, 23 Oct 1999 10:24:28 PDT

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




Previous by Author: RE: Usable Specs?
Next by Author: Usable Specs=DFDs
Previous by Thread: Re: Any ideas for a presentation on the documentation process?
Next by Thread: RE: Any ideas for a presentation on the documentation process?


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

Sponsored Ads


Sponsored Ads