No subject given

[Michael Burke <miburke -at- WSICORP -dot- COM>]

     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