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:Re: Department of Redundancy Dept. From:Matt Hicks <matt -at- UNIDATA -dot- UCAR -dot- EDU> Date:Fri, 17 Jun 1994 14:47:26 -0600
On Fri, 17 Jun 1994, nancy ott wrote:
> This is the message that the UNIX version of Framemaker displays when
> you fire it up:
> : Before using FrameMaker for the first time, be sure to read
> : the online manual "Changing Setup Files" for information on
> : configuring Frame products for use with various window managers.
> Now, how am I supposed to read the on-line manual BEFORE running the
> software??
I don't think this qualifies as nonsense, redundancy, or any other
documentation faux pas.
First off, let's not confuse running the software with using it; ever buy an
electrical gadget and just turn it on to make sure it works? Sure you ran it,
but you didn't use it. I generally do the same thing with software--I
just want to make sure the thing starts up and displays before I set my
sights on actually producing anything with it.
Secondly, in the UNIX environment, getting something to display is only
half the battle. If you do not have the appropriate resources set,
_using_ the software will be frustrating at best. My initial experiences
with running Framemaker were not much fun until I got in and made some
changes to the setup files.
I think that this is both an appropriate and an appropriately placed
message. We all know how impatient a user can be--how they want to just
jump right in--and the good folks at Frame (I'm a fan of this package)
want to make sure that you consider the impact that your window manager
has on the application's performance. Since the package will run without
these window-manager specific alterations, the only way the documenters
could be reasonably confident that you would see this caveat was to
display it when the application started up. If the application wouldn't
run without these changes, then they could simply cover the issue in a
troubleshooting section of the manual, but they couldn't rely on that
here. Neither could this be covered in the installation section: at many
sites (my own included) users choose which of several window managers
they want to use and the setup files determine how the window adornments
will appear on each users terminal.
I think that the obfuscation/redundancy witchhunt has yielded its first
innocent victim.
-----------------------------------------------------------------
Matt Hicks, Tech. Writer, Unidata * You can make statistics say any-
Boulder, CO, (303)497-8676 ******* thing, especially if you grill them
matt -at- unidata -dot- ucar -dot- edu ************* under hot lights for a few hours.
