tuba@ur-tut.UUCP (Jon Krueger) (03/05/86)
In article <460@utastro.UUCP> nather@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@UORDBV Taylor Hall Phone: (716) 275-2811 work, 473-4124 home Rochester, NY 14627