11.0128 when bad writing was BAD

Humanist Discussion Group (humanist@kcl.ac.uk)
Sun, 22 Jun 1997 10:26:17 +0100 (BST)

Humanist Discussion Group, Vol. 11, No. 128.
Centre for Computing in the Humanities, King's College London
<http://www.princeton.edu/~mccarty/humanist/>
<http://www.kcl.ac.uk/humanities/cch/humanist/>

Date: Fri, 20 Jun 1997 10:16:59 -0700
From: Mary Dee Harris <mdharris@acm.org>
Subject: Re: 11.0121 bad writing

> Software manuals are often, as we all know, very bad indeed. Apart from the
> author's simple incompetence with the written language, many of those I've
> seen suffer from a common failure of imagination. Prima facie evidence
> suggests very strongly that the authors of these things simply cannot
> imagine that their readers do not know what they know. I've picked up many a
> manual that never actually says what the software in question is, rather it
> launches immediately into details of how to do X, sometimes without saying
> what X is either, or why one would want to do it.
<snip>

> Comments?

When I first worked for IBM as a programmer back in the olden days
(1960's), I was considered quite talented because I could READ the
manuals and comprehend their meaning and intent. And even better I
could explain it all to other people. In those days there was no such
thing as a *user*; even the 'programming' manuals were written by and
for the engineers. There were few explanations of any sort, certainly
no algorithms, simply technical (VERY) description of the execution
cycle of each assembly language instruction. We were supposed to figure
out the rest. I never saw any instructions for something like operating a
computer, which we did have to do on occasion to test our programs.

I've always wondered how my academic background of mathematics, German,
and English literature prepared me for that! I guess that's why we call
it education and not training!

Mary Dee

-- 
Mary Dee Harris, Ph.D.			512-477-7213
Language Technology, Inc.		512-477-7351 (fax)
2415 Griswold Lane			mdharris@acm.org
Austin, TX 78703			mdharris@aol.com