No subject given

Subject: No subject given
From: Hope Cascio <hope -dot- d -dot- cascio -at- US -dot- ARTHURANDERSEN -dot- COM>
Date: Fri, 22 May 1998 12:59:21 -0400

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


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

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.


Michael Burke
Technical Writer
WSI Corporation
Billerica, MA

Previous by Author: Is grammar important?
Next by Author: RoboHelp 6.0
Previous by Thread: Re: No subject given
Next by Thread: No subject given

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

Sponsored Ads