TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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.
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
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
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.