Unix docs

[Jon Krueger]

In article <460 at utastro.UUCP> nather at utastro.UUCP (Ed Nather) writes:
>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, you are absolutely right.

I wrote an introductory guide to Unix for local use at the University of
Rochester.  I took a bold step in computer documentation: I wrote it in the
active voice.  I used "I" or "we" when I meant the Unix consultant or the
Computing Center.  I used "you" when I meant the user.  I used "Unix" when I
meant Unix, the shell, or the computer.  I took these three agents and made
them the subjects of active sentences.  In my document, people do things to
Unix, and Unix does things to people.  Acts are not done upon objects by
unnamed agents.  When I expect the user to do something, I say "you must do
this".

I will be happy to send copies of this guide to anyone.  Since I have
neither time nor money to send the typeset hardcopy, I am limiting this offer
to people who can accept machine-readable copy.  Currently, I am maintaining
it in Microsoft Word on a Macintosh.  If you have Microsoft Word running on
a Mac, I can send it to you over uucp in this format.  Otherwise, I can send
you a "text only" version.  You will find a Laserwriter highly desirable,
since I depend on high quality fonts to express some points.

Please note that I limit the scope of this Guide.  It will tell you how to
login and out of Unix, it describes the Unix documentation, basic shell
commands, briefly describes the vi editor, gives Unix commands to use
languages and manipulate text, mentions Unix mail, usenet and uucp, and a
few hints.  In the most recent version, I added sections on job control,
history, and piping and i/o redirection.  It won't tell you how to develop
code under Unix, or make system calls, or use make, or anything of that
sort.  Also note that it's filled with U of Rochester localisms.

If you're interested, mail me at the uucp address given below.  Please
include a string "unix guide" somewhere in your message.

					-- Jon Krueger

UUCP:	...seismo!rochester!ur-tut!tuba  USMAIL: University of Rochester
BITNET:	TUBA at UORDBV				 Taylor Hall
Phone:	(716) 275-2811 work, 473-4124 home	 Rochester, NY  14627