No subject given

Subject: No subject given
From: Michael Burke <miburke -at- WSICORP -dot- COM>
Date: Fri, 22 May 1998 12:50:31 -0500

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




Previous by Author: Re[2]: TECHWR-L Digest - 14 May 1998 to 15 May 1998
Next by Author: Re[2]: Employment Agencies - Technical Communication Specifi
Previous by Thread: No subject given
Next by Thread: more light


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

Sponsored Ads


Sponsored Ads