Return-Path:<@k.cs.cmu.edu:day@H.CS.CMU.EDU> Received: from K.CS.CMU.EDU by A.CS.CMU.EDU; 5 Dec 85 12:58:25 EST Received: from H.CS.CMU.EDU by K.CS.CMU.EDU; 5 Dec 85 12:53:19 EST Date: 5 Dec 1985 12:49:50-EST From: David.Yaskin@H.CS.CMU.EDU To: bovik@k Subject: User Manual Responses Messages from /usrh1/day/mail.hg: 71? 24 Nov 85 Bob Colwell ; Sun, 24 Nov 85 20:45:21 est; Date: Sun, 24 Nov 85 20:45:21 est From: Bob Colwell Message-Id: <8511250145.AA17214@faraday.ECE.CMU.EDU> To: day@h Subject: manuals I've always thought the Scribe manual is about the best technical manual I've ever had to use. It only seems to fail me when Scribe itself does, and that's all you can ask of a manual. Bob ---- Message 74 (594 chars) is ---- Received: from SPICE.CS.CMU.EDU by H.CS.CMU.EDU; 24 Nov 85 22:09:18 EST Date: 24 Nov 1985 22:06-EST From: Daniel.Zigmond@SPICE.CS.CMU.EDU Subject: Re: Good User Manuals To: David.Yaskin@H.CS.CMU.EDU Message-Id: <501736008/djz@SPICE.CS.CMU.EDU> In-Reply-To: David.Yaskin@H.CS.CMU.EDU's bboard message of 24-Nov-85 20:26 Please keep me informed of the replies you get, I am writing a user manual and am also collecting good ones. I like Guy Steele's "Common Lisp: the Language" but it is not really geared for novices. I think it is a great technical reference manual, however. Dan ---- Message 75 (344 chars) is ---- Received: from C.CS.CMU.EDU by H.CS.CMU.EDU; 24 Nov 85 22:38:15 EST Received: ID ; Sun 24 Nov 85 22:39:29-EST Date: Sun 24 Nov 85 22:39:28-EST From: Maurice.Herlihy@C.CS.CMU.EDU Subject: reference manuals To: day@H.CS.CMU.EDU Message-ID: <12161948688.29.HERLIHY@C.CS.CMU.EDU> How about the CLU reference manual? ------- ---- Message 76 (1212 chars) is ---- Received: from A.PSY.CMU.EDU by H.CS.CMU.EDU; 25 Nov 85 00:40:08 EST Date: Monday, 25 Nov 85 00:30:35 EST From: charney (davida charney) @ a.psy.cmu.edu Subject: user manuals To: yaskin @ h.cs.cmu.edu You might want to look at the 2-volume "Guide to TOPS-20 Computing" produced by the Communications Design Center at CMU. It is available in the bookstore and many other places. It is one of the first and very few manuals that was completely user-tested. It is well-organized, clear and usable. Another more technical manual is Chris Neuwirth's guide to the Andrew window manager. You might be able to get a copy from Sandra Bond who's in charge of documentation at the ITC (x6713). She was on the team that produced the TOPS-20 guide and knows almost everything there is to know about user-friendly manuals. If you want counter-examples, let me know. I've got a slew of horror stories. For the record, I've spent the last 2.5 years (with Lynne Reder) doing experimental research on what needs to go into a computer manual to make it more effective. I'd be interested to hear why you're asking -- you don't happen to be taking a course in document design by any chance? Davida ---- Message 77 (663 chars) is ---- Received: from A.CS.CMU.EDU by H.CS.CMU.EDU; 25 Nov 85 03:16:38 EST Date: 25 Nov 85 03:15:30 EST From: Dave.Touretzky@A.CS.CMU.EDU Subject: Re: Good User Manuals To: David.Yaskin@H.CS.CMU.EDU I think the documentation that comes with the IBM PC (in particular the DOS guide and the operations guide) is very good. As an experienced computed user new to the PC, I was able to navigate my way through the manual with no trouble at all. There are lots of examples, which helps. Another good and much larger documentation effort is the set of 10 manuals that come with the Symbolics Lisp Machine. They are extensively indexed, including a KWIK index. -- Dave ---- Message 78 (672 chars) is ---- Received: from IUS2.CS.CMU.EDU by H.CS.CMU.EDU; 25 Nov 85 09:46:08 EST Date: 25 Nov 1985 09:42-EST From: Leonard.Hamey@IUS2.CS.CMU.EDU Subject: Re: Good User Manuals To: David.Yaskin@H.CS.CMU.EDU Message-Id: <501777778/lgh@IUS2.CS.CMU.EDU> In-Reply-To: David.Yaskin@H.CS.CMU.EDU's bboard message of 24-Nov-85 20:30 In my opinion, the VAX/VMS manuals comprise one of the best written sets that I have seen. For the novice, there are tutorial introductions. For instance, an editor manual. For the expert, the required information is available. At Macquarie University, Sydney Australia, the students use VAX/VMS exclusively and they make good use of the manuals. ---- Message 79 (1684 chars) is ---- Date: 25 Nov 1985 09:39-EST From: Eddie.Caplan@H.CS.CMU.EDU To: yaskin Subject: user manuals Message-Id: <501777583/egc@H.CS.CMU.EDU> the only good user manual i have ever seen is the Scribe manual. it contains the following features (ordered novice to expert): 0. clear writing. the authors chose a conversant style, closer to what one would find in a novel rather than in terse technical manuals. 1. the first few paragraphs tell what the author assumes the reader knows, and where to find that information if the reader DOESN'T know. 2. the novice learns how to use simple scribe in the first dozen pages. ("You now know how to use scribe...just don't use any @ signs in your text.") 3. the information is accurate and correct. nothing's worse than a manual which is MOSTLY correct, but sometimes incomplete. 4. clear table of contents. 5. extensive index. this is a pet peeve of mine. it annoys me no end when i it takes 6 or more tries at the index to find the entry i need, or to find that no entry exists. scribe has entries like "changing things" or "when things go wrong". these are great for novices. remember, anyone who is looking something up in the manual probably does not know what he is looking for exactly. he needs help to guide him to the right place in the manual. frequently, indexes are organized in the same way that the technical information is organized. that's fine for readers who pretty much know what they are looking for but can't remember the details of syntax, for example. in most ways, the table of contents can tell me the same information. so i expect more from the index. eddie ---- Message 80 (438 chars) is ---- Received: from FARADAY.ECE.CMU.EDU by H.CS.CMU.EDU; 25 Nov 85 10:58:01 EST Received: by faraday.ECE.CMU.EDU (4.12/4.7) id ; Mon, 25 Nov 85 10:32:14 est; Date: Mon, 25 Nov 85 10:32:14 est From: Dan Nydick Message-Id: <8511251532.AA26311@faraday.ECE.CMU.EDU> To: david.yaskin@h Subject: manuals The Scribe manual isn't TOO bad... (available wherever hacker congregate, or ask any secretary). -Dan ---- Message 81 (55348 chars) is ---- Received: from A.CS.CMU.EDU by H.CS.CMU.EDU; 25 Nov 85 11:05:20 EST Date: Mon, 25 Nov 85 11:05 EST From: Craig.Everhart@A.CS.CMU.EDU To: day@H.CS.CMU.EDU Subject: Messages about manuals from a while ago Message-Id: <25Nov85.110509.CE10@A.CS.CMU.EDU> - - - - Begin forwarded message - - - - Mail-From: ARPANET host SUMEX-AIM received by CMU-10A at 12-Jul-82 14:33:32-EDT Mail-from: SU-NET host SU-SHASTA rcvd at 12-Jul-82 1120-PDT Date: Monday, 12 Jul 1982 08:50-PDT To: Everhart at CMUA Subject: survey messages, all 44 of 'em Reply-to: BKR at SU-AI From: Brian Reid ------- Forwarded Messages Mail-from: SU-NET host Sail rcvd at 10 May 1982 19:48:33-PDT Date: 10 May 1982 2240-EDT From: Matt Reilly at CMU-10A@Shasta at Sumex-Aim Subject: Re: documentation quality survey To: Brian Reid Best: sorry to say that it is the IBM Programmer's Reference Manual for Fortran H/ H extended/ G. I hate all of thier manuals for OS/VM/CMS stuff, but the Fortran manual stands out for its succinctness, completeness, and ease of use. I gave mine away when I became ashamed of using fortran. Sadly, the IBM PL/1 manual was not nearly as usefull. Worst: PASCAL User's Manual and Report (Jensen and Wirth) The index is not nearly complete and is totally useless. They used section numbers instead of page numbers, and then didnt put the section number at the top of every page in the section! matt ------- Message 2 Mail-from: SU-NET host Sail rcvd at 10 May 1982 19:51:32-PDT Date: 10 May 1982 22:37-EDT (Monday) From: FEINBERG at CMU-20C@Shasta at Sumex-Aim To: Brian Reid at CMU-10A Subject: documentation quality survey Howdy! Could you post a pointer to the results of your survey. I would be very interested in them. The best manual is experience. You need a good text to help along, though. Perhaps the best manual was the one for SNOBOL (I forget the exact name and author, although it is the famous one which poplarized the language). It's the one they used in 15-312 last fall. I don't like SNOBOL, but the manual was very understandable and clear. ~ ------- Message 3 Mail-from: SU-NET host Sail rcvd at 10 May 1982 20:32:24-PDT Date: 10 May 1982 2310-EDT From: Craig Everhart at CMU-10A@Shasta at Sumex-Aim Subject: Re: documentation quality survey To: Brian Reid Hm. I don't have a clear favorite manual, though SAIL's manual is OK (especially for such a large language). Why? Probably because they delay discussion of basic things like what constitutes a declaration and things until the end of it, thus telling you that your basic intuition about Algol constructs is valid. The manuals I dislike are the ones that don't start by giving a context for what they're talking about. They're both reference manuals, but they seem to feel it's OK if you try to learn from them, since they view the programming language as a kind of proof where you have to define terms before they're used. Instead, they should try to give you some idea of the fundamental metaphors of the language. My two bad examples: The Bliss manual. (The one I tried to learn from was Bliss-10; Bliss-11 doesn't seem to be any better; I haven't looked at the common Bliss manuals to verify how they are.) First of all, Bliss is a programming language in the Algol family, so some simple programs would help make things clear. At the beginning of the manual, please, not some arcane Newcomer hacks at the end; they serve a different purpose. The fundamental metaphor behind Bliss-10 is machine arithmetic and memory schemes; the tools by which Bliss accesses the machine are the name-as-byte-pointer (or, more generally, name-as-pointer), constants, and the dot operator. From this and some discussion of what a procedure call is, you can deduce how to use the rest of the language, and you should be told how those constructs are used to do simple four-line routines/programs. Right; then go to procedure calls. Then records, and you show how structures work and how pointer mapping works, and you can go pretty far. What Bliss-10 gives is a grammar. The Pub manual. It took me a long time to realize what Pub did, to merge somehow the idea that I could take a random text file and run it through Pub and have a formatted copy come out, with the reference manual that told me tha Pub was a programming language that had variables and assignments and bizarre control constructs and things. In both these cases I really wanted a basic metaphor for how to use what the language was trying to provide. Instead, I get formal rigor in the Bliss case, and complete confusion in the Pub case. I believe that staged presentation of a language is valuable and necessary. You should be able to take whatever documentation a language provides and, after getting through some minimum number of chapters, be able to write some minimal working program. Probably this is why I even think of the Sail manual as anything reasonable; you don't have to read the second half to write simple programs, without Leap or processes. If you come up with any conclusions, I'd like to hear about them. I'm doing relatively formal work in a related area, which you could casually title ``What I did for my summer vacation, and for the next five years.''Trying to write up and generalize from all the software engineering I've wound up doing. We shall see if the faculty buys it as a thesis topic. Hope life is treating you well. Craig ------- Message 4 Mail-from: SU-NET host Sail rcvd at 10 May 1982 20:45:48-PDT Date: 10 May 1982 2337-EDT From: Robert Frederking at CMU-10A@Shasta at Sumex-Aim Subject: Re: documentation quality survey To: Brian Reid (a) Best is a toss up. Several completely usable ones come to mind, such as the CWRU Algol manual or Motorola's 6800 manual. The wonderful thing about both of them was a thorough (and correct) index, and (at least for the 6800), an accurate description of *exactly* what the machine instruction did, including embarassing details like the fact that the X register didn't incr properly. (b) Wirth's Pascal tutorial. The index doesn't contain what I need, and implementations always vary. It doesn't specify everything, and the implementors usually don't bother to adequately document what's left. Bob ------- Message 5 Mail-from: SU-NET host Sail rcvd at 10 May 1982 21:24:28-PDT Date: 11 May 1982 0013-EDT From: Scott E. Fahlman To: reid at CMUA cc: fahlman at CMU-20C Subject: Manual survey Message-ID: <820410001342FAHLMAN@CMU-20C> Brian, I don't really have any nominations for best manual. There are no manuals for currently-existing Lisps that I am at all fond of, and I haven't noticed anything much better in my sparse forays into the barbarous tongues. A programming language reference manual has to be clear, accurate, complete, up-to-date well-orgainzed and indexed. It also has to be of finite size: it is hard to conceive of an effective paper manual for something as huge as PL/1 or Interlisp, though an online tree-structured manual might cut it. Given all that (and it is not given very often) the manual sort of becomes invisible and what you remember is the quality of the language. If we move from reference manuals to related materials, there are some ways to rise above the pack. There should (somewhere, not in the reference manual) be a clear presentation of the following issues: * How to use any novel features of the langauge. * What tricks (if any) will make your code run more efficiently. * What is considered to be good programming style in the language. * How to use the language's debugging aids. * What libraries and tools exist and where you can find them. * Examples of good code in the language. Also, you get extra credit if the documentation is online in some easily-usable form (i.e. better than the Unix online manual). As I said, I have no nominations. My favorite manual is that for Emacs, by Richard Stallman, which exists both in paper and online forms, but that is not a programming language. I do have a couple of nominations for worst manual. The first is Maclisp, whose manual is bad because it doesn't exist. The definitive documentation consists of a collection of five or so years' worth of incremental update messages. An old manual by Dave Moon is out of print and hopelessly obsolete anyway. Several more recent attempts to create a manual died short of completion, for assorted institutional reasons. My second nomination for worst manual (though it amounts to beating a dead horse) is the Lisp 1.5 Manual, by McCarthy, et al. This document single-handedly convinced a whole generation of programmers that Lisp was hairy and unusable. In fairness, the manual is obscure and overly hairy, but it reflects the Lisp of its day; the real problem is that this manual remained in use, without revision, even after Lisp had evolved into something much cleaner than it was in the early days. The real blame, then lies not with the authors of this manual but with those who allowed this book to remain the standard text for nearly ten years, by which time Lisp had changed almost beyond recognition. -------- ~ ------- Message 6 Mail-from: SU-NET host Sail rcvd at 11 May 1982 03:32:57-PDT Date: 11 May 1982 0622-EDT From: BUTCHER at CMU-20C@Shasta at Sumex-Aim Subject: programming manuals To: reid at CMU-10A Hi. THought I would put my two bits in. The best manual I have used would be the jensen and wirth Pascal manual. The worst would be the C manual. They are both organized in the same way, both typeset pretty good, and both the same size. However the Pascal book has Pascal pictures. Those pictures are just about the only thing I look at for routine problems. They make a big difference. Butcher ------- ~ ------- Message 7 Mail-from: SU-NET host Sail rcvd at 11 May 1982 06:50:24-PDT Date: 11 May 1982 09:35:27-EDT From: Nathaniel.Borenstein at CMU-780G at CMU-10A@Shasta at Sumex-Aim To: brian.reid@cmua Subject: Language manuals The best I've ever worked with is the C Book (I think it's called @i(The C Programming Language) -- you know the one). It is good because it is filled with genuinely useful examples; often you can copy whole routines out of it and modify them only slightly for a number of purposes, and this kind of modifying-existing-code is probably one of the best ways to learn the proper style of a language. Also it is very clearly written, well organized, and nicely typeset, which also help, but I think it is examples that make the book. Everything that the C book is, the SAIL manual isn't. What a piece of trash. Once you get past the HORRIBLE typesetting (which is hard to do) you are face to face with a manual that seems to have been written for people who only think in PDP-10 assembly codes. As far as I can tell, the organization of the manual bears no relation whatsoever to human categories of thought. Examples are more-or-less nonexistent. (Yes, these are the admittedly biased observations of a non-SAILor who naively volunteered to maintain bboard, but I'm still one SAILor who wishes he'd never left the C.) I hope you'll make some sort of statistical summary of your results public. I'm very curious to see how other people respond, but I'd prefer not to wade through a mail file with all the answers... -- Nathaniel ------- Message 8 Mail-from: SU-NET host Sail rcvd at 11 May 1982 08:10:04-PDT Date: 11 May 1982 1039-EDT (Tuesday) From: Karen.Hensley at CMU-10A@Shasta at Sumex-Aim To: Brian Reid at CMU-10A Subject: Documentation Message-Id: <11May82 103944 KH80@CMU-10A> a) Scribe manual is the best. Lets you start with a little and build on. Everything about it is right. b) UNIX documentation is the worst. Everything about it is obscure. If you want to find out how to get a hard copy of something none of the following keywords are indexed anywhere: Dover, print, lineprinter, lp . . . If you want to ship a file to another machine the ftp documentation is unreadable, it says something about [qewpio...] or such as that. I could go on but the basic complaint is that a person who is an expert in TOPS or VMS can login to a IBM operation system & use it immediatly. A person well versed in TOPS and VMS and IBM-CMS cannot just sit down at at UNIX machine and do usable work reading documentation as s/he goes. ------- Message 9 Mail-from: SU-NET host Sail rcvd at 11 May 1982 08:10:07-PDT Date: 11 May 1982 1032-EDT From: Gregg Podnar at CMU-10A@Shasta at Sumex-Aim Subject: Manuals To: Brian Reid Brian, Even though the book as a whole is pretty austere, the Jensen & Wirth Pascal manual is my vote for best because the whole language is avail- able in BNF and flow diagram on about 6 pages. Concise reference. The standard WATFOR/WATFIVE IBM reference (once you come to use IBMs vocabulary) is very complete. Again as a reference. DECs manuals are pretty sad. Althou Although the information may all be contained, finding it is difficult due to poor organization and indexing. I've learned the languages from the above mentioned manuals. But, I learned to program from a human instructor. I don't believe there is a better way. (I've never used programmed materials). ------- Message 10 Mail-from: SU-NET host Sail rcvd at 10 May 1982 14:16:55-PDT Date: 10 May 1982 1409-PDT From: g.Beecher at SU-SCORE (Ben Beecher)@Shasta at Sumex-Aim Subject: Re: best manual? To: BKR at SU-AI In-Reply-To: Your message of 10-May-82 1322-PDT By far the best manual I've seen is "The C Programming Language" by Kernighan and Ritchie. In the "worst manual" category I'd like to nominate the Burroughs COBOL manual. It's even worse than the Burroughs ALGOL manual (which is awful). Their COBOL manual tries to imitate the style of IBM manuals in general but is confusing and full of mistakes. Very dry reading. /Ben Beecher ------- ------- Message 11 Mail-from: SU-NET host Sail rcvd at 10 May 1982 14:26:04-PDT Date: 10 May 1982 1421-PDT From: Mike Spreitzer Subject: Prog Lang Man Survey To: BKR at SU-AI I like the "APL/360 Reference Manual", by Sandra Pakin. It gives the full and precise details of each operator, and is organized in a way that makes the information easy to find. That is, it is a great reference manual. It is less suited to be used as a tutorial. But it is not too difficult to learn an interactive language with a terminal in front of you and a good reference manual in hand. ------- ------- Message 12 Mail-from: SU-NET host Sail rcvd at 10 May 1982 14:31:31-PDT Date: 10 May 1982 1426-PDT From: Mike Spreitzer Subject: more Prog Lan Man survey To: BKR at SU-AI For the worst manual, I place the PASCAL User Manual and Report in a tie with the Mesa docs. The PASCAL thing is at least all in one piece, but I can never find what I'm looking for. Also, I think it is less than complete and precise (maybe I've just never found all the info). Mesa, on the other hand, has the problem that, in addition to a basic language, has a big cloud of system surrounding it. Tracking down what documentation there is is a challenge, and once you get it it is often sketchy. ------- ------- Message 13 Mail-from: SU-NET host Sail rcvd at 10 May 1982 14:31:51-PDT Date: 10 May 1982 1426-PDT From: Ed Falis Subject: Re: best manual? To: BKR at SU-AI In-Reply-To: Your message of 10-May-82 1322-PDT I CAN'T THINK OF A BEST MANUAL OFFHAND, BUT MY VOTE FOR THE WORST EASILY GOES TO THE MACLISP REFERENCE MANUAL: POORLY ORGANIZED, NO INDEX, INNACURATE AND INCOMPLETE. GORIN'S ASSEMBLY MANUAL IS PRETTY GOOD IN MY OPINION, AS IT INTRODUCES CONCEPTS NICELY CONSIDERING ITS SCOPE. THE CURRENT ADA MANUAL IS ALSO PRETTY POOR, PARTIALLY THROUGH UNCLARITY AND PARTIALLY THROUGH LANGUAGE AMBIGUITIES. I TAKE IT YOU'LL BE ANNOUNCING YOUR RESULTS ON THIS? - ED ------- ------- Message 14 Mail-from: SU-NET host SUMEX-AIM rcvd at 10 May 1982 16:06:23-PDT Mail-from: ARPANET host SU-SCORE rcvd at 10-May-82 1600-PDT Date: 10 May 1982 1559-PDT From: Richard Treitel Subject: best manual To: reid at SU-SHASTA cc: CSL.VER.RJT at SU-SCORE at SUMEX-AIM ... was probably the WATFIV, though it has been a long time now. The YORK APL manual was pretty good too. Worst is undoubtedly my Maclisp manual, due to lack of decent index and information never being in the section where you would expect to find it. It is a colossal pain to use. Innerlisp runs a close second due to sheer size, complexity, duplicity, and incorrectness. (I also can't stand the Innerlisp language) - Richard ------- ------- Message 15 Mail-from: SU-NET host Sail rcvd at 10 May 1982 18:06:54-PDT Date: 10 May 1982 20:56:47-EDT From: Hank.Walker at CMU-VLSI at CMU-10A@Shasta at Sumex-Aim To: reid@cmua Subject: programming manuals The best one that I've used is Simula Begin, by Dahl, etc. It's a book, and nicely introduces the concept of a class. Object-oriented programming was completely new to me, and reading the book was sufficient to understand it well. The worst I've read is probably something like Meet MACRO-10 or Introduction to 370 Assembly-Code Programming, probably because they can't rise above the level of the language. ------- Message 16 Mail-from: SU-NET host Sail rcvd at 10 May 1982 18:12:29-PDT Date: 10 May 1982 2108-EDT From: Don.Cohen at CMU-10A (C410DC01)@Shasta at Sumex-Aim To: Brian.Reid at CMU-10A Subject: Language manual Message-Id: <10May82 210824 DC01@CMU-10A> In my only slightly biased opinion, the best manual isthe cmulisp manual. The most important reason is that it is a helpo system on line (I never actually read the manual). Also, it is quite complete and well indexed in the sense of a zog net. For more info r lisp on cmua. My candidate for worst is an early eclipse microcode manual which may have been comprehensible to those who already understood it, but not to me. ------- Message 17 Mail-from: SU-NET host Sail rcvd at 10 May 1982 19:00:10-PDT Date: 10 May 1982 21:50:32-EDT From: Bruce.Lucas at CMU-IUS at CMU-10A@Shasta at Sumex-Aim To: reid@cmua Subject: language manuals The C Reference Manual has much to recommend it. It is well-organized, mostly contains just the information you need, and is neither too stuffy nor too chatty. Its most serious drawback is lack of an index, but this is not a fundmental flaw (i.e. it could be remedied without rewriting the manual), and the manual's organization and conciseness largely compensate for this. ------- Message 18 Mail-from: SU-NET host Sail rcvd at 10 May 1982 19:03:30-PDT Date: 10 May 1982 2159-EDT (Monday) From: Kevin.Nolish at CMU-10A (L170KN15)@Shasta at Sumex-Aim To: Brian Reid at CMU-10A Subject: Programming Language Manuals Message-Id: <10May82 215949 KN15@CMU-10A> The key to any programming language text or refrence manual is EXAMPLES,EXAMPLES, and LOTS MORE EXAMPLES. The C REFRENCE MANUAL by Ritchie and Kernighan (Forgive my spelling) is a good introduction to the language. It combines a tutorial, a style book, and a refrence manual into one easy to use volume. What makes it good is the fact that the examples are not contrived to show off the language. A real problem, say a storage allocater, is discussed and then a C implementation is shown. THe book shows how to fit the language to a problem. Most texts that I've read tend to express an artificial problem that is perfectly solved by, oh lets say, a WHILE loop. Unfortunantly, this doesn't give the reader a sense of what the language can and, more importantly, what it CANNOT do. Another very good manual is the Bliss-36 refrence manual. In this manual DEC often explains the motivation behind language constructs. Thus the constructs seem natural and are easy to use.(Granted this is not a good choice for a beginning reader) As for bad books, Grogino's pascal book (Title escapes me) struck me as pretty bland. It seemes to be yet another treatement of a language that has too many books written for it. KNolish P.S. Keep in mind that I'm more of a machine hacker than most people are. Consequently I find that I tend to prefer manuals with more implementation information in them simply because I tend to do strange things like link modules written in different languages together. ------- Message 19 Mail-from: SU-NET host SUMEX-AIM rcvd at 11 May 1982 08:20:47-PDT Mail-from: ARPANET host SU-SCORE rcvd at 11-May-82 0816-PDT Date: 11 May 1982 0814-PDT From: Kenneth P. Brooks Subject: best manual To: reid@shasta at SUMEX-AIM The best manual I ever read is the standard SNOBOL manual - the big green one. It is so simply and lucidly written that I digested it with good comprehension at one sitting, almost. It has SYSTEMATIC PRESENTATION and in difficult places it has EXAMPLES with GRAPHICAL ILLUSTRATIONS. In considerable contrast is the standard Pascal manual, for reasons I cannot put my finger on. Perhaps the type face has quite a bit to do with it! But it is not a joy to read, and by no means fills the reader with delight at the thought of using the language. But certainly the worst manuals I have seen were IBM system utility manuals. Big and ugly, describing programs with utterly un-mnemonic names. That was long ago, and I don't remember much except that the manuals, like the systems they described, were far too big and ponderous for a casual user to use. Kenneth ------- ------- Message 20 Replied: 11 May 82 09:06 Mail-from: SU-NET host Sail rcvd at 11 May 1982 08:49:00-PDT Date: 11 May 1982 11:37:44-EDT From: Philip.Wadler at CMU-750Y at CMU-10A@Shasta at Sumex-Aim To: brian.reid@cmu-10a Subject: best and worse Brian, My favorite language documentation is Kernighan and Ritchie's book on the C programming language. I think what I like best is that there are many real programs (including i/o and other often ignored stuff) that provide models I can go to when I write programs. Part of this is that Kernighan is a good writer. Part of this is that C/Unix is a good system, and has things like standardized i/o. It is hard to provide good documentation for a system that can vary from place to place. Which brings me to my least favorite example: The Scribe manual. Although the authors know how to write, many of the most important details concern particular document formats which may vary from place to place, and so are omitted. This can make the manual very frustrating to use. Another problem is that the language itself depends on many idiosyncratic features that deal with specific cases. This makes it hard for the manual to be organized in a uniform way that makes it easy to look things up. (For instance, I looked in vain for a way of putting an environment into italics -- the index was no help. Finally, someone explained @begin{foo, use i} to me.) It would help immensely to standardize the formats and include these in the documentation. (Despite these harsh words, I still find Scribe to be a useful tool.) -- Phil ------- Message 21 Replied: 11 May 82 09:09 Mail-from: SU-NET host Sail rcvd at 11 May 1982 08:53:34-PDT Date: 11 May 1982 1150-EDT (Tuesday) From: Jeff.Shrager at CMU-10A@Shasta at Sumex-Aim To: brian.reid Subject: Programming language manuals Brian, I have seen many good and many very bad manuals but never one that I would call very good. Here is a listing in approximate order of decreasing goodness on several scales. All scales are rated on a 1-5 basis except the overall rating which is on a 1-10 basis. This covers a bit more than programming languages. I thought others might be interesting. Also, some books are the manual (like the snobolIV by G.P.andP.) Scale legend: A- Tutorial utility (for beginners) B- Expert utility (for looking up an error or something) C- Interest estimate (would you take it to the John) D- Overall rating (1-10) Text A B C D ---- - - - - Snobol 4 (by Griswald et al) 10 7 9 8 IBM 360 APL (or APL.SV) 8 9 7 8 PDP-8 assembler (brown book) 9 5 8 8 IBM PL/1 O.C. manual set 8 10 5 8 InterLisp 7 8 9 8 Univac APL.MS 7 7 6 7 DEC VMS programming languages 4 6 4 5 Scribe 4 5 3 4 DEC-10 (TOPS) PL manuals 3 6 2 4 Maclisp 1 4 1 2 Unix System 0 0 0 0 There are lots of others but I don't have time to think about them right now. Perhaps I'll continue this list later on. The shot at the Unix manual isn't fair since it's not a PL manual but I couldn't resist. -- Jeff PS: Why the interest? ------- Message 22 Mail-from: SU-NET host Sail rcvd at 11 May 1982 09:20:32-PDT Date: 11 May 1982 1203-EDT From: Rick Gumpertz at CMU-10A@Shasta at Sumex-Aim Subject: Re: documentation quality survey To: Brian Reid I very much enjoyed A FORTRAN COLORING BOOK by Roger Kaufman (?spelling?) which is published by MIT Press. It's primary problem is that it is about Fortran. Sigh. I found it very easy to read and very much to the point. I don't know, however, how it would have been had I not already known the subject. Therefore, I am not sure I can give it a fair evaluation. For worst programming language manual, choose ANY manual published by Pr1me. Absolute worst has to be the Assembly Language Programmer's Manual, or whatever it is called (something close to that, anyway). After 4 months of use I am still not sure how many user-addressable registers there are in the machine! More comments on request--I don't want to burn up the ARPANET during transmission of this message unless you really want them. Rick ------- Message 23 Mail-from: SU-NET host Sail rcvd at 11 May 1982 10:01:35-PDT Date: 11 May 1982 1257-EDT (Tuesday) From: Ed.Gehringer at CMU-10A (C300EG60)@Shasta at Sumex-Aim To: Brian.Reid at CMU-10A Subject: PL manuals Message-Id: <11May82 125718 EG60@CMU-10A> Off the top of my head (after 2 min. meditation), I'd recommend the Burroughs B6700 Algol manual and the CDC 6500 Cobol manual (!) as among the best I've ever used. It's been several years (>=6) since I've used either, but as I recall, the best attribute of them was that they contained comprehensive information on each statement or construct in a single section of the manual, and also that the prose was fairly fluently written, not choppy like in most manuals I've seen. Some of the "worser" manuals I've used were the CDC 6500 Aspol manual and the Sail manual. The former suffered from not having an index, making frequent linear searches necessary. In fact, the easiest way to discover anything was to look at the sample program in Chapter 1. If you couldn't find it there, you'd have a hard time finding it. The Sail manual suffers from the effects of poorly integrated extensions and updates, which makes it hard to find comprehensive information on a topic in a particular place. It also has an overstuffed plastic binding which makes pages very hard to turn. -Ed ------- Message 24 Mail-from: SU-NET host Sail rcvd at 11 May 1982 10:02:32-PDT Date: 11 May 1982 1258-EDT (Tuesday) From: Lee Shombert at CMU-10A@Shasta at Sumex-Aim To: Brian Reid at CMU-10A Subject: documentation quality survey Message-Id: <11May82 125806 LS60@CMU-10A> My vote for the best programming language manual goes to the C text by Kernighan and Ritchie. The Pascal report (from Springer-Verlag) counts as one of the more difficult to use, partly from the poor production. There are too few examples in the book and extensions to ideas are sometimes glossed over, making the actual syntax unclear (to me). To be fair, I was new to Pascal, and the report is not supposed to teach the language. ------- Message 25 Replied: 11 May 82 11:52 Mail-from: SU-NET host Sail rcvd at 11 May 1982 10:14:44-PDT Date: 11 May 1982 1010-PDT From: Bob Weissman Subject: Re: best manual? To: BKR at SU-AI In-Reply-To: Your message of 10-May-82 1322-PDT The best programming language manual I have used is the Interlisp manual. I like it because it's very well cross-referenced and indexed, so it's easy to find what you need despite its enormous size. It has (Ed McMahon accent here) EVerything you ever wanted to know about Interlisp and a lot more besides. The worst programming language manual is clearly Wirth's Pascal book. There's no way to find anything without reading through the manual each time. I'd be interested in seeing the results of your survey. -- Bob ------- ------- Message 26 Mail-from: SU-NET host Sail rcvd at 11 May 1982 10:58:46-PDT Date: 11 May 1982 1025-PDT From: Joan Feigenbaum Subject: Re: best manual? To: BKR at SU-AI In-Reply-To: Your message of 10-May-82 1322-PDT the best programming language manual i've ever used was the C book by kernighan and ritchie. also, volume two of the UNIX programmer's manual, which is really just a collection of papers about the various utility programs, is one of the most readable pieces of documentation i've ever used. the worst was friedman's "the little lisper". it has the same romper room style as patrick winston's ai book, and that style (which i think some authors feel is "non-threatening" or something) makes me want to vomit. let me know the results. joan ------- ------- Message 27 Mail-from: SU-NET host Sail rcvd at 11 May 1982 11:25:51-PDT Date: 11 May 1982 1419-EDT (Tuesday) From: Victor.Milenkovic at CMU-10A@Shasta at Sumex-Aim To: Brian.Reid at CMU-10A Subject: documentation Message-Id: <11May82 141938 VM80@CMU-10A> I can not remember very many manuals that I have read, but a few come to mind. THE LITTLE LISPER (I forget the author's name) is an interesting if not slightly infantile way to learn beginning Lisp. The TRS-80 BASIC manual is pretty silly too, but I think it is fairly well written. On the other side of the coin, IBM manuals are very dry and would often be improved by a few examples. Also they require one to make "Talmudic" interpretations; e.g., "if thingy was not allowed then they would have said so here, and so thingy must be allowed." Finally, the ADA manual contains a mixture of rigor and untimely examples that make it confusing and incomprehensible. Victor Milenkovic ------- Message 28 Mail-from: SU-NET host SUMEX-AIM rcvd at 11 May 1982 17:36:30-PDT Mail-from: ARPANET host SU-SCORE rcvd at 11-May-82 1731-PDT Date: 11 May 1982 1728-PDT From: Judy Anderson Subject: Programming language manuals To: reid@shasta at SUMEX-AIM The best programming language manual (well actually a textbook of sorts) is the Fortran Coloring Book (which I used to learn fortran after already knowing pascal). Next best I would say is Ralph's DEC-20 assembler book. I'll have to give the other category some thought; can't come up with a real bad one right off the bat... Judy. ------- ------- Message 29 Mail-from: SU-NET host Sail rcvd at 11 May 1982 17:42:52-PDT Date: 11 May 1982 2039-EDT From: Jon.Bentley at CMU-10A (C300JB31)@Shasta at Sumex-Aim To: Brian.Reid at CMU-10A Subject: Manuals Message-Id: <11May82 203948 JB31@CMU-10A> The best manual of all time is, of course, A22-6821: the System/360 Principles of Operation. It is clear, concise, accurate, useful, and useable. If you weren't who you are and already insufferably arrogant about being a supernova on the horizon, I would toss in the Scribe manual as having many of the same features (but you are, so I won't). Interesting to note that both were written by two people--that number has some amazing properties for documents. Here is a novel entry (I hope) for worst--most of the personal computer literature. It is written entirely as a tutorial, and is horrible as a manual. I refer in particular to the TRS-80 system manual, but the genre in general is suckitudinous. A notable exception (and almost into the above category) is the new IBM manuals for their PC--if you haven't seen the documentation, find some immediately. Now that I think of it, it is among the best reference manuals that I have seen. Sorry for the random flames--I'm too tired. Good luck. Jon p.s. Don't take the hassle seriously. Being almost up there with me in insecurity, you are nowhere near arrogant enough. p.p.s. My regards to the little woman. ------- Message 30 Mail-from: SU-NET host Sail rcvd at 11 May 1982 18:08:24-PDT Date: 11 May 1982 1802-PDT From: ICL SKIL Root Subject: Re: best manual? To: BKR at SU-AI In-Reply-To: Your message of 10-May-82 1322-PDT Best - Starting Forth by Leo Brodie Worst - of course PL-I manuals are in a class by themselves, but most introductory Pascal books are up there. ( Exception - Grogono ). Most introductory books make the mistake of trying to be jazzy tutorials that the student can read without learning. He doesn't know that he knows nothing and is in deep trouble until he has gone in about 200 pages. Starting Forth makes this mistake too, ( too many cartoons ), but considering the mixed audience and sales constraints ( Must sell forth inc. forth, which has a lot of problems) it's not bad. In general programming manuals should be hard to read, but they should be short and devoid of lies and inaccuracies. ------- ------- Message 31 Mail-from: SU-NET host Sail rcvd at 11 May 1982 20:43:23-PDT Date: 11 May 1982 2038-PDT From: Scott Meyers Subject: Best/worst language manuals To: bkr at SU-SCORE Best: The Snobol4 manual that we used in cs142. Worst: Nicky and Kathi's book on PASCAL, for obvious reasons. Scott ------- ------- Message 32 Mail-from: SU-NET host Sail rcvd at 12 May 1982 03:28:23-PDT Date: 12 May 1982 0325-PDT From: Stuart McLure Cracraft Subject: survey To: reid at CMU-10A The best programming language manual/intro I have read is the Kernighan/Ritchie collaboration `The C Programming Language'. I liked it because it was clear, concise, had good examples, and for once assumed that the reader knew the basics of programming. The quality of the print was high and the organization was well-planned. The second best introduction to a language I have read is Pat Winston's 2nd half of Artifical Intelligence where he discusses MacLISP, probably the only readable LISP intro I have seen. The worst language manual I have read is the Fortran manual published by DEC. Various manuals on PL/1 are also pretty poor. I've only glanced through Xerox's MESA manual, but would like to read more. ------- ~ ------- Message 33 Mail-from: SU-NET host Sail rcvd at 12 May 1982 05:09:40-PDT Date: 12 May 1982 0805-EDT From: Joseph Ginder at CMU-10A@Shasta at Sumex-Aim Subject: Re: documentation quality survey To: Brian Reid I really like "The Little Lisper" by Dan Friedman, published by SRA. It's a tutorial introduction to traditional Lisp programming. ------- Message 34 Mail-from: SU-NET host Sail rcvd at 12 May 1982 11:12:18-PDT Date: 12 May 1982 1107-PDT From: Neil Rowe Subject: programming manuals To: csl.bkr at SU-SCORE 1. best is Hal Abelson's new Logo manual (forthcoming from Byte books). (a) represents 15 years of refinement (b) is nontechnical (c) is interactive (d) introduces procedures in the first chapter. 2. many "worsts", but the SAIL manual (the big one) is a strong competitor. Cluttered with useless features, poorly organized. ------- ------- Message 35 Mail-from: SU-NET host Sail rcvd at 14 May 1982 08:16:21-PDT Date: 14 May 1982 1113-EDT From: eddie caplan at CMU-10A@Shasta at Sumex-Aim To: brian reid Subject: documentation brian, best: the pascal manual. not only is it well organized as a reference once i've got the hang of the manual, it's well structured for the relatively novice programmer. i can usually find things in the index when i want them. also, as a tutorial, they are not afraid to put off details for later chapters when it blurs what they are trying to tell me NOW. worst: the pdp-10 assembly language manual. all of the strong points of the pascal manual are weak or downright bad in the macro manual. there is no help to the novice (at least a novice to assembler). "why would a novice want to program in macro?", i hear you ask naively. it happens. often. i can't find things in the index unless i already know what they are called. i get nitty-gritty details in the middle of a high level discussion. and the writing style is so goddam dry! i don't need to be addressed like an infant, but i'm not a machine either. the pascal manual, for instance, treats me like an intelligent adult who just happens to not know anything about its language. personally, i like lots of indexing. if a concept is compared to the preparation of french toast in the text, i expect to find "french toast" in the index. this example is such a colorful description, that i'll will always think about french toast first. i want the index to be pointers from what i am thinking, to where i can find out about it. the scribe manual does ok, but right now there is someone sitting next to me who can't find anywhere in the manual about the placement of pictures inside of the body of the text. i also like a clear macro structure. the organization of the chapters should make sense. also, the breakdown of information within the chapters should be divided into sections and subsections if appropriate. i also like bzm's tingle documentation. his organization is very clear, separating the expert information from the novice's. eddie ------- Message 36 Mail-from: SU-NET host Sail rcvd at 15 May 1982 09:59:59-PDT Date: 15 May 1982 0955-PDT From: Dan Lynch Subject: Bet/worst To: Reid at SU-SCORE cc: Lynch at USC-ISIB Brian, The best manual I ever read was the Fortran Autotester. It is a very old self teaching type of book. I have my original copy of it. One of the authors was a Doris Johnson. I have very strong feelings about it. I picked it up one morning and read/worked it for the rest of the day and wrote my first program that afternoon. It was a 13 line prime number genrator and it worked on the first attempt! I have since done less well... In second place is Gorin's book on SLOPS20 assembly language programming. Last place is just too crowded. Perhaps the NLS documentation wins... Dan ------- ------- Message 37 Mail-from: SU-NET host Sail rcvd at 14 May 1982 09:56:20-PDT Date: 14 May 1982 1207-EDT From: Jan Walker Subject: Re: best and worst? To: BKR at MIT-MC In-Reply-To: Your message of 14-May-82 1117-EDT Funny. I had been vaguely tempted to say that the only language textbook I remember learning a whole lot from was the SNOBOL4 one. so your sister will be living with you for the summer? Maybe this experience will help hook her on computers as well as on California. ------- ------- Message 38 Mail-from: SU-NET host Sail rcvd at 15 May 1982 11:25:26-PDT Date: 15 May 1982 1414-EDT From: Jack Mostow at CMU-10A@Shasta at Sumex-Aim Subject: Re: documentation quality survey To: Brian Reid Brian - Off-hand, I'd say the best programming language manual I've used is the Scribe designer's manual, because its extensive index makes things easy to find. No insult intended by "Scribe" ~ "programming language". (Actually, the most trouble I had finding out things about Scribe was when I was macro hacking for my thesis and using features you wanted kept secret. As you may remember.) The worst manual I remember is the pdp10 assembly language manual from a decade ago, which was written so poorly that its explanations made sense only if you already understood the point being explained. I.e., it didn't seem like anyone asked themselves, "what will this mean to somebody who doesn't know it already?" Regards to you and Loretta. - Jack ------- Message 39 Mail-from: SU-NET host Sail rcvd at 17 May 1982 08:40:46-PDT Date: 17 May 1982 1121-EDT From: Joe Newcomer at CMU-10A@Shasta at Sumex-Aim Subject: Re: documentation quality survey To: Brian Reid One of the truly worst manuals I have ever used is the Jensen/Wirth Pascal manual. Inadequate indexing, indexing based on sections (but the sections are not clearly labelled, e.g., "A." instead of "1.A"), two indices for the two different sections of the manual, omission of almost all of the interesting keywords or builtin procedure names one might want to refer to. An example in every way of how to NOT do a manual. It is probably one of the most incompetently done manuals I have had the misfortune to have to use. I consider the SNOBOL IV manual one of the better ones I have used; I don't like its examples, but the typography, index, and explanations make it possible to actually learn SNOBOL even if you've never seen it before (I hadn't). One which is marginal is the old McCarthy LISP primer; what detracts from it is the M-expression/S-expression distinction. I have read the Pat Winston LISP manual and found it MUCH better (I was reading it with a critical eye because someone wanted to learn LISP and I was doing an evaluation of this manual). I'd put Winston's LISP manual up towards the top of the list. I haven't tried to use its inde, so can't evaluate it onat basis. However, if I had to use it to learn LISP, I think I would rank it quite high. Another good manual for the experienced LISP programmer is the UCI LISP manual. I used it EXTENSIVELY for two years, and found its index complete and its descriptions clear and adequate. Its editor section I thought was particularly clear (with a couple exceptions) and the details of how to extend the editor, top-level, read-macros, etc. were written well enough that I never had to refer to the assembly code (the standard MACLisp technique, I'm told) to find out what was going on. I find the SAIL manual adequately indexed, and the explanations for most of the system are complete and accurate. The process section and the LEAP sections are abysmal, so I'd not rate the overall manual very high. My criteria, as you may have already guessed, are: complete index of all reserved words, language constructs, runtimes, data types, and anything else one might have to randomly access complete, clear descriptions of each such feature, without verbose examples, or references to too many other sections of the manual. In particular, by "complete", I mean that if "reference" parameters are implemented by "value-result" mechanism, this is made clear; nothing is glossed over or hidden so as not to "confuse" the user. documentation is written for the professional programmer. Someone who knows a couple langauges and has to learn a new one. Something that carefully and meticulously explains what a FOR-loop is is NOT a language manual; it is a language tutorial. Tutorials are fine, but they shouldn't interfere with the concise complete description of a language feature or runtime procedure. joe ------- Message 40 Date: Monday, 17 May 1982 13:07-PDT To: reid at Shasta Cc: sap at Shasta Subject: Manuals From: Steve Przybylski The worst programming language manual I recall ever having to use was a maclisp manual. The functions were listed in groups of about 5 to 10 according to some common aspect - such as arithmetic, predicates, list operators, etc. The problem was that there were no examples. Thus as a novice, I had no idea what look for or how to do things. It had a very poor index and no introduction. I can't remember ever using a manual and thinking .. wow this is a great manual. I feel that most manuals, particularly for programming languages need to serve three different needs: 1. Introduction of potentially new concepts to the first time user. 2. General information on how to use it for the intermediate user, including many examples of a wide range of complexity to show how the language is best used. and 3. Detailed information for the intermediate and advanced user who has forgotten something or is unclear about the specifics. The words that are to satisfy these three needs should be separated or at least easily distinguished. Invariably, I am always in one of the three modes, and all the other stuff just gets in the way. I think the C Programming language book does a good job of this, and of the number and style of the examples ( introducing new ideas/features by rewriting a previous example ). Gilman and Rose does this but fails to provide a good dense, well cross referenced summary of details for the experienced user who wants to know which dimension /[2] is. This multilevel presentation is more important as the systems become complex. The perfect example is the OS manual that lists all the commands in order in full gory detail- ideal for the experienced but frustrating for any non-wizard trying to see if there is a command to do foo and not sure what it might be called. A separate section containing the more common or fundamental commands without all their switches and options would help a lot. One idea sometimes used in newspapers that I think would be applicable is the use of different type fonts to distinguish information of different levels of detail. Most of the better manuals have used fonts to differentiate between text and code, but stop at that. I could probably ramble on a fair bit longer about this, and would be glad to if it would be appreciated. Steven ------- Message 41 Replied: 11 May 82 15:01 Mail-from: SU-NET host Sail rcvd at 11 May 1982 10:59:12-PDT Date: 11 May 1982 1350-EDT From: Jeanne Halpin at CMU-10A@Shasta at Sumex-Aim Subject: Re: documentation quality survey To: Brian Reid Brian, I'd be interested in what you find on this topic because my advisor, Dick Hayes in Psychology, is doing research on document design, including computer manuals. As a matter of fact, he will be working on redesigning the H&SS's Pascal manual this summer. If you're interested in what he has found or knows, let me know and I'll pass the word on to him (he has an account on CMU-A but never uses it, so mail direct to him is not a good idea until you let him know that that is a desirable way to interact with you--he can be convinced to get on the machine for that purpose, I'm sure.) --Jeannie Halpin-- ------- Message 42 Replied: 14 May 82 08:10 Mail-from: SU-NET host Sail rcvd at 14 May 1982 07:14:18-PDT Date: Friday, 14 May 1982, 10:10-EDT From: Jan Walker Subject: best and worst? To: BKR at MIT-MC Hmm. I am not familiar with many @i[manuals] for programming languages. My favorite manual at the moment is the EMACS users manual, but this is not one for a programming language. Also, I assume you are making a distinction between a text book about a language and a reference manual for the language. I've seen some reasonable textbooks but none of them would function as a manual for a language (because they always leave out or gloss over the hardest part of any language, which is doing high volume IO sensibly). A reference manual I would like would have information at all levels from really basic stuff through complex issues. It would define terminology carefully and use it consistently. It would be full of cross-references to related concepts. It would have examples of the language being applied to the kinds of problems that it had been designed to solve. It would have an index of conceptual terms, not just language keywords. As for organization, it would have a section explaining the major concepts of the language and talking about which language features fit into which categories. It would have a big reference section that treated each feature independently, so you could find the information fast. Actually one manual I have used that is organized like this is the TECO reference manual from MIT. It works extremely well. One file does the conceptual stuff and stuff about conventions; one file has a complete reference listing of everything; the sources for EMACS itself provide the best possible set of examples. Nothing I have used anywhere else even comes close. The closest is the TOPS-20 Monitor Calls Users Guide and Reference Manual (2 separate books). It is pretty good but lacks real explanation for terms, concepts, and conventions and has no examples. Manuals that I dislike very much are the Pascal User Manual and Report and the BBN BCPL manual. The Pascal Report fails on most of the counts above. It is too short to be functional. Wirth has this stupid idea that any language worth designing can be described in 25 pages or less. Anyone can get inside that limit by leaving out the kinds of sentences necessary for an ordinary person to understand it. The only good thing about the Pascal Report is the syntax diagrams. The BCPL manual is equally bad (with no syntax diagrams) but at least it wasn't published between stiff covers. They both suffer from a really arrogant formal language-designer-ese style. Probably what you get from most people when you ask whether something is "a good manual" is some rating based on whether they were able to do the job they needed to do either using or in spite of the manual. If they managed to get the job done, they probably think that the manual is fine. (Maybe it is.) Now for the meta-question. Why on earth are you doing this survey? Of course I would like to hear about the results (as well as about anything that you are up to). ------- Message 43 Mail-from: SU-NET host DSN rcvd at 23 May 1982 11:53:04-PDT Mail-from: Arpanet host SU-SCORE rcvd for reid@SU-SHASTA at 23-May-82 11:32:39-PDT Date: 23 May 1982 1131-PDT From: Peter Ullman Subject: best manual To: reid at SU-SHASTA Hi: I may have read the BBOARD message a little too late, but nevertheless, you may still be having the survey. (1) The best programming manual that I ever read was the TRS-80 LEVEL I BASIC manual. In case you want to know why, it was just about the funniest manual that I ever read (then again, just about the only manual that I ever read. Aside from being funny, it was quite instr- uctive. (2) Although I never finished reading it, the worst manual that I think that I ever read was PASCAL: AN INTRODUCTION TO METHODICAL PROGRAMMING. After just the first chapter, it not only bored me to death, but even to the point that I didn't even think that I was learning PASCAL (after reading a little more of that book, I still don't think that I know the first thing about PASCAL. --Peter-- ------- ------- Message 44 Mail-from: SU-NET host Sail rcvd at 26 May 1982 18:24:17-PDT Date: 26 May 1982 2119-EDT From: HEDRICK at RUTGERS (Mgr DEC-20s/Dir LCSR Comp Facility)@Shasta at Sumex-Aim Subject: documentation quality To: brian.reid at CMU-10A best) The problem is that I don't remember them all that well, since it has been many years ago for a number of them. So I'll give you a couple. Algol 60 Revised Report - it was short, precise, complete (or at least it seemed complete - the "Remaining Problems ... " suggests that maybe there were a few holes), just generally elegant. I don't hold with verbosity. Jensen and Wirth shares many of those virtues, and indeed I think it is well written. However when you try to use it you find that there are too many questions it doesn't answer. I guess part of the virtue of the Algol 60 Report is the fact that the languages itself is elegant. Scribe Introductory User's Manual, First Edition - It was not quite a concise as the Algol 60 Report, but it was also clear and precise. The current manual from Unilogic is similar, and shares most of the virtues, but they have removed a little of the wit and made the examples a bit more pedestrian. The changes are very minor, but are noticable if you put them side by side. worst) Algol68 Reference Manual - who could make any sense out it? They thought they were being precise, and maybe they were, but essentially what they did was to produce an interpreter that interpreted Algol68 source and was written in a programming language that no one could read. I claim they could have accomplished the same thing and been more intelligible if they had written an interpreter in Algol60. 2nd worst) any of the IBM PL/I manuals. They are complete, and even fairly well organized (I like the idea of the first half being conceptual description and the second half reference), but there are too many rules whose implications are hidden until you fall over them. There are too many cases where they say: use the following algorithm (2 pages long, requiring reference to 3 charts) to figure out what this construct means. ------- ~ ------- Message 45 Date: 15 June 1982 17:35:20-PDT (Tuesday) From: trg@Shasta at Sumex-Aim Subject: hit list To: reid You once asked for comments on manuals etc, here are my comments: Category "Programming Languages": WORST: ALGOL68 documentation, language report, everything. A language you can't understand unless you understand it already. GOOD: Pascal user manual. (I care less for the report) and the LOTS Pascal documentation. The user manual is well written, tells you all you ever wanted to know and can be read once a year. The Pascal documentation is quite a ccurate. I thought for a second that I am biased towards Pascal (over C, LISP), but then try the following test: you want to write a simple program and set a breakpoint at line x. Start with "help pascal" at Score and "man cc" at Shasta. Category "Text Processing": WORST(known to me): TEX manual. Ever tried to get a slightly ambitious document done? The manual is almost no help, all you get are messages telling you that you can't do this in "restricted horizontal mode". Absolute turn off. GOOD: Bravo and Scribe. Problem with Scribe is that the manual describes the general picture, whereas there are lots of local changes. Category "Operating Systems": WORST: IBM CMS (although other IBM OS might actually be worse). Impossible to find any help at all. Good for recycling centers, these manuals contain lots of paper. BAD: UNIX programmer manual. If you don't know it you won't find it. I find the UNIX documentation (as used by a user, not a system programmer) extremely annoying. The only way to learn seems to be to look over your neighbours shoulder. And the "man" program makes things even worse. You forget about one flag and you have to skim over tons of text. Even you could use the editor for te manual pages, things would be better. GOOD: ? This was an account of the manuals, not the software product (However I prefer Unix to CMS). thomas ------- End of Forwarded Messages - - - - End forwarded message - - - - ---- Message 82 (370 chars) is ---- Received: from GANDALF.CS.CMU.EDU by H.CS.CMU.EDU; 25 Nov 85 12:59:43 EST Date: 25 Nov 1985 12:59-EST From: Benjamin.Pierce@GANDALF.CS.CMU.EDU To: David.Yaskin@H.CS.CMU.EDU Subject: Re: Good User Manuals Message-Id: <501789552/bcp@GANDALF.CS.CMU.EDU> In-Reply-To: David.Yaskin's bboard message of 24-Nov-85 20:27 My favorite is the Scribe manual. Benjamin Pierce ---- Message 83 (285 chars) is ---- Received: from K.CS.CMU.EDU by H.CS.CMU.EDU; 25 Nov 85 14:46:38 EST Date: Monday, 25 November 1985 14:45:10 EST From: Michael.Young@k.cs.cmu.edu To: day@h.cs.cmu.edu Subject: Re: manuals Message-ID: <1985.11.25.19.44.41.Michael.Young@k.cs.cmu.edu> Um, your file is overly protected. ---- Message 84 (449 chars) is ---- Received: from SPICE.CS.CMU.EDU by H.CS.CMU.EDU; 25 Nov 85 16:06:58 EST Date: 25 Nov 1985 16:04-EST From: Michael.Jones@SPICE.CS.CMU.EDU To: David.Yaskin@H.CS.CMU.EDU Subject: Re: Good User Manuals Message-Id: <501800690/mbj@SPICE.CS.CMU.EDU> The best manual I know of is the Common Lisp manual/book by Guy Steele, available in the bookstore, or from most of the AI researchers here. Also probably available in the E&S library. -- Mike ---- Message 86 (756 chars) is ---- Received: from CAD.CS.CMU.EDU by H.CS.CMU.EDU; 25 Nov 85 18:00:09 EST Date: 25 Nov 1985 17:56-EST From: Dragon Subject: Re: Manual Responses To: David.Yaskin@H.CS.CMU.EDU Message-Id: <501807378/mjc@CAD.CS.CMU.EDU> In-Reply-To: David.Yaskin@H.CS.CMU.EDU's bboard message of 25-Nov-85 12:41 Scribe? Come now. The Scribe manual has the annoying property of saying "you can do this wonderful thing; see the DBA for details." Do you know how hard it is to come by a Database Administrator's guide? For a beginner, the scribe manual is ok (it's probably too much for a total beginner, but maybe not). My recommendation for a technical manual that is informative and well-organized is the Common Lisp Manual. -D ---- Message 89 (455 chars) is ---- Received: from LEG.RI.CMU.EDU by H.CS.CMU.EDU; 26 Nov 85 12:46:28 EST Date: Tuesday, 26 November 1985 12:43:26 EST From: Jeff.Koechling@leg.ri.cmu.edu To: day@h.cs.cmu.edu Subject: Manuals Message-ID: <1985.11.26.16.57.31.Jeff.Koechling@leg.ri.cmu.edu> I like "The TeXbook" It's real comprehensive, and well indexed, and well written. It has gradations of detail for novice up to ultra-hacker It has lots of examples. It has cartoons and jokes and wit.