No subject given

[Hope Cascio <hope -dot- d -dot- cascio -at- US -dot- ARTHURANDERSEN -dot- COM>]

I think an important consideration is whether you think users with no UNIX
background would be likely to begin using this feature of the program, if
they were given enough information to use it comfortably.  If the only
people who are likely to use this feature, anyway, are hard-core UNIX
people, then you should write only to them.  I don't think something "in
the middle" is likely to be valuable, if your audience is not "in the
middle," but rather on either end of the spectrum.

Hope Cascio

___________________________________________________________________________
_________________________________________________________________

To:     TECHWR-L @ LISTSERV.OKSTATE.EDU
cc:      (bcc: Hope D. Cascio)
From:   miburke -at- WSICORP -dot- COM
Date:   05/22/98 01:50 PM
Subject:  No subject given
___________________________________________________________________________
_________________________________________________________________




     Hello --

     I am currently involved in a dilemma over how to present some
     information in a user manual.

     I am updating a user manual for a software application that runs on
     UNIX systems. Until now, 100% of the user interaction with the
     application came through the UI. I have never made reference to UNIX
     anywhere in the book.

     Now, there is a utility that has been built into the system that can
     only be run in UNIX. My dilemma is how to present the information on
     this utility and how to use it. There is a single, configurable
     command string that a user would enter, producing a tabular text
     report on screen.

     The users of this application have little or no knowledge of UNIX. But
     those few users who are likely to use the utility do have strong UNIX
     background.

     Is it better to:

     1. Write about the utility to only those with strong UNIX backgrounds,
     addressing the minority of the application users, but the majority of
     those who will use this particular function? With scant info about
     what the UNIX command means, and just give the configurable
     parameters. As though it were a useful MAN page.

     2. Write towards those with no UNIX background, thus addressing the
     vast majority of the application's users. Including heavy detail on
     the UNIX command structure, changing directories, using UNIX text
     editors etc.

     3. Find a middle ground between the two with enough detail so as not
     to scare off the non-UNIX people, while not talking down to those
     well-versed in UNIX.

     I am leaning towards the third option, including some description of
     the UNIX environment, a breakdown (with figure) of the different parts
     of the command line, a brief discussion of the JOT text editor.

     Has anyone run into a similar situation? By that I mean, having to
     introduce operating system commands into a GUI manual?

     I would appreciate any insight that you can offer.

     Thanks


     Michael Burke
     Technical Writer
     WSI Corporation
     Billerica, MA