Relay-Version: version B 2.10 5/3/83; site utzoo.UUCP
Path: utzoo!watmath!clyde!burl!ulysses!gamma!epsilon!zeta!sabre!petrus!bellcore!decvax!genrad!panda!talcott!harvard!seismo!ut-sally!utastro!nather
From: nather@utastro.UUCP (Ed Nather)
Newsgroups: net.unix
Subject: Re: article i posted that died
Message-ID: <460@utastro.UUCP>
Date: Mon, 3-Mar-86 11:58:19 EST
Article-I.D.: utastro.460
Posted: Mon Mar  3 11:58:19 1986
Date-Received: Wed, 5-Mar-86 05:46:21 EST
References: <443@polaris.UUCP> <6452@utzoo.UUCP>
Organization: U. Texas, Astronomy, Austin, TX
Lines: 26

In article <6452@utzoo.UUCP>, henry@utzoo.UUCP (Henry Spencer) writes:
> > the documentation needs improvement.
> 
> Still a problem area.  Although the documentation for most other systems
> also needs improvement, for different reasons:  it drowns you in verbiage
> and detail.  One thing Unix does *not* need is documentation that is
> "improved" to that point.
> 				Henry Spencer @ U of Toronto Zoology

That "verbiage" that is so opaque often consists of passive constructions
which totally obscure the point to be made.  As an example, from the
Microsoft C (v3.0) manual:

"If more than one flag is present, they are separated by the "|" symbol ..."

By whom?  Me, or the compiler?  After experimenting, I found it *should* say
"If you include more than one flag, you must separate them with ..."

This type of construction is depressingly prevalent in documentation of all
kinds on all systems.  It should be taken out and shot.

-- 
Ed Nather
Astronomy Dept, U of Texas @ Austin
{allegra,ihnp4}!{noao,ut-sally}!utastro!nather
nather@astro.UTEXAS.EDU