mitch@well.UUCP (Mitchell Waite) (03/02/88)
In article <495@apple.Apple.Com> winkler@Apple.COM (Dan Winkler) said: > As the author of the HyperTalk language and as an Apple employee, I am going to refrain from endorsing or criticizing any particular HyperCard book. However, I will say that there are some very poor ones out there that were thrown together in a matter of weeks and that are full of inaccuracies and examples that are not even syntactically correct (i.e. they were never tried). I feel there is a need for some informed criticism of these books in forums like this. I do not feel that the reviews I have seen so far have been informed. Folks, you shouldn't post a message to thousands of people around the world endorsing a book (or anything else) that you haven't thoroughly studied. I can't be the one to tell you that any particular book is dog meat, but I desperately want you to figure it out on your own and you haven't been doing too well so far. > I think it is pretty obvious why the newest books out on HyperTalk are so poor in quality but it may not be as clear to others, so here goes my 8 bits. As a computer book author and programmer, with over 70 books on the market, who started in 1974, I believe I am in a position to make some fairly accurate observations about the book publishing field. First, this phenomena of "quickly put together" computer books on new programming languages, operating systems, and software products has been going on for over 12 years. It started in 1974 when CP/M books came out and showed that there was a growing market for trade computer books (trade means in the book stores). Up till that point the most popular books where on CMOS and TTL (Don Lancaster was the Danny Goodman of electronics at that time. Audio books and Walter Jung where also hot). These first CP/M computer books where hastily written, often devoid of substance, inaccurate, and, in most cases, just plain worthless. But people bought them! And threw them away. And publishers grew out of the woodwork. They put colorful covers, titles that promised power and mastery overnight. Yet out of the over 100 CP/M books published, only three of four where any good. What happened was that over the years the good books continued to sell, and the others ended up collecting dust on the bookstore shelves, and got sent back to the publishers as "returns" (returns are like payments you didn't know you had to pay-publishers hate them). The the good books eventually sold well and some of these CP/M books are in fact still selling today! This phenomena was followed by every major product in the microcomputer market place: Apple //, Visicalc, BASIC, MS-DOS, IBM-PC, WordStar, 1-2-3, Pascal, C; each of these had tons of early out junk books, followed later by more solid tutorials, application and reference titles. The forces at work that produce these early books are interesting. In general the software creator (be it Digital Research, Lotus, whoever) do a crummy job of documentation. It is done last and fast. This leaves a giant hole for improvements in the documentation and in some cases the manufacturer never fills the hole (CP/M and MS-DOS manuals are an example, the best selling computer book in the world is Using 1-2-3 and its not from Lotus. We won't even touch on UNIX books). So the computer book publishers see a great opportunity with these poorly documented products. This would not be such a bad situation except many of the publishers still are driven by the fact that in the beginning people will buy anything, and beginners will not know if its a good or a bad book, and these publishers will automatically gain market share if they move quickly. And quickly they move. In fact the quickest write the book BEFORE the product is out. The Goodman book is a classic case of this out-the-door-quick-for-market-share phenomena for HyperCard (published by Bantam who is a late starter in computer books). The Shafer book (published by Sams) is a classic case of out-the-door-quick-for-market-share for HyperTalk. In the first case, Apple knew it was behind on Wildcard and needed to get a product out the door fast. This explains the proliferation of quirky bugs still in the product (and I love HyperCard still so don't take this wrong). They worked hard on there own manual, but alas not everyone is satisfied with it. Plus at least 50 to 75% of the HyperCard users get HyperCard someway other then by purchasing it, and don't ever see a manual. Apple's decision to bundle HyperCard added more fuel to this last possibility. They made a deal early with Bantam to bring in Goodman and let him get the first book out. This was a great deal for Bantam, for Apple, for Goodman, and really it wasn't so bad for the book buyer because at least the book wasn't written in a vacuum, and had an opportunity to be looked over by the tough eye of Apple. And as a HyperCard training book, Goodman's title is not that bad. But as a HyperTalk primer, it is the pits. And that is understandable since Goodman is not a programmer and never admits he is one. Overall I think more people win then loose here and don't have a lot of gripes about the Goodman book and Apple's approach. I only wish they picked me to write it. The first book out on HyperTalk was from Walking Shadow Press: "Programming with HyperTalk". The Walking Shadow book is distributed by a couple guys at Apple and to this day has no real distribution in book stores and so is not really a valid entry (yet). Content wise it has some interesting scripts, and the first three chapters are pretty good, but it falls apart after that. The Shafer book (HyperTalk Programming/Hayden/Sams) was the first HyperTalk programming title from a major publisher (Sams is owned by Macmillan, and Sams owns Hayden). This book was written very fast (under 4 months), was desktop published by the author to avoid the slow typesetting production cycle, and has sold over 30,000 copies in just three months. <possible flame on> In my opinion the Shafer book is lacking in many ways. First, its organization is all over the map, it covers too many things, from stack products to authoring. The sequence for teaching the subjects of HyperTalk is non-linear, things are lumped together in a confusing fashion, like lumping all the dialog boxes in one chapter, when they are really related to many different topics. I also find it dumps at the very beginning a huge amount of detailed authoring information that is easily forgotten and doesn't belong in the book. I find the examples to be lacking and that they don't represent typical problems I run across when I program. There are NO flowcharts anywhere, not even in the section on control structures. There are only two project scripts, one is an education quizzer the other a script writing prototyper neither of which are very useful in my opinion. There are few tricks, little about me, and so on. The best part to me is the 23 page Appendix A which gives the entire HyperTalk vocabulary, its syntax and notes about each command, function and keyword. Its also expensive ($24.95 for a book on a product that cost $49.00). On the other hand if I had to teach HyperTalk today there is little else to choose from so I would probably turn to this book, but create my own path for the student to follow rather than follow its table of contents. <possible flame off> The way things will turn out is that the Shafer book will sell until a better book comes out. <unabashed plug on - skip if you don't trust me> My company is working on such a HyperTalk programming book that is combination tutorial and reference. Our formula is not to be the first out, but to be the best out. The book has three top notch authors all working together, meeting every week to review each others progress. We spent two months just designing the outline. Every example is written and tested before the text is written. Every chapter builds on previous knowledge and no ad-hoc assumptions are made. We have three separate technical reviewers at work. There is a stack being written that will give a HyperCard version of the information (much like the way the Texas database program works). There will be a section containing the 100 most asked programming questions about HyperTalk, garnished by long hours studying the pattern of questions people ask nets (BIX, usenet, and Compuserve). It will be reviewed by Dan Winkler. The first two thirds is tutorial. The second third of the book is a reference of each command, with three examples in a standard format (each example more complex than the one before it). Caveats, bugs, tips and warnings are given for each command. There is a quicker short form reference to, and jump tables on the inside and back covers contain all the keywords with pointers to the reference and tutorial pages. The book is called HyperTalk Bible and will be available in the fall of this year. I will announce the book when it is out here and on the other nets. <unabashed plug off> There will be other good books out on HyperTalk. Publishers like Microsoft Press and Que tend to do a very good job on their titles. Bantam is hard at work on two more script titles from Goodman and I know for a fact that every major computer book publisher has at least two HyperTalk books in the works. By the first quarter of 89 I would expect about 20 books to be on the market. Hopefully this will clear up some of the thoughts people may be having about the early HyperTalk books. In the end I think that Dan Winkler is correct when he asks people to be careful when they say a book is good. What are your qualifications for saying a book is good? Good compared to what? A detailed analysis of a book is even more difficult than analysis of a software program. There is no way to test if a book "crashes", unless you sit and type in the scripts, and how many reviewers do that? Sincerely, Mitchell Waite
stephena@microsoft.UUCP (Stephen Arrants 3/1011) (03/03/88)
In article <5346@well.UUCP>, mitch@well.UUCP (Mitchell Waite) writes: >.......... In general > the software creator (be it Digital Research, Lotus, whoever) do a >crummy job of documentation. I'd say in *very* general. Computer documentation has really come a long way in the past few years. >It is done last and fast. I don't think you understand the process of documentation from the inside at all. In all the companies I've worked, the docs never came "fast and last". The documentation team at Microsoft, for example, is included in product development from the start. Recommendations and input from the doc. team is an important part of the total design. The documentation can take as long as the product development. >This leaves a giant hole for > improvements in the documentation and in some cases the >manufacturer >never fills the hole [ ] Nope. What leaves these holes are: 1. Changes to the software that can't make it into the documentation because the books are either finishing the run at the printer or that the books are in the warehouse waiting for the software to arrive for shipping. 2. Cost of Goods. If a product sells to a distributor for, say $200, COG can be 15% -- $25. That's $25 for the package, disks, disk labels, keyboard templates, collateral materials, registration card, and documentation. Let's say that the documentation itself is 10% ($20) COG. I don't think that software companies are doing too poor a job. The manuals MUST be comprehensive. Third party books rarely are. 3. Errata sheets and README files. These are caused by #1 above. Documentation must ship with the software. Third party books don't have to ship with the software. >[......]In fact the quickest write the book BEFORE the product is out. What's wrong with that? You give the impression that the author has no idea what s/he's documenting. A *good* author of a third party book will work with the development, marketing and documentation teams before the product ships. Many, many authors use the company's own documentation as an important source for their own books. Must be something good there for an author to rely on it. > Mitchell Waite -- Steve Arrants stephena@microsof.beaver.washington.edu Applications/UserEd. stephena%microsof@uw-beaver.arpa Microsoft Corp. stephena@microsof.uucp Opinions posted are mine, not my employer's. So there.
chuq@plaid.Sun.COM (Chuq Von Rospach) (03/03/88)
[As one of the people who been saying nice things about Shafer's book, here and in a book review I just turned in for Macintosh Horizon's magazine, I'll stick my electronic foot in mouth and comment on both Dan and Mitchell's comments] > dan: >However, I will say that there are some very poor ones out there >that were thrown together in a matter of weeks and that are full of >inaccuracies and examples that are not even syntactically correct >(i.e. they were never tried). I feel there is a need for some >informed criticism of these books in forums like this. I do not feel >that the reviews I have seen so far have been informed. Folks, you >shouldn't post a message to thousands of people around the world >endorsing a book (or anything else) that you haven't thoroughly >studied. Dan's right, but not completely. There is a lot of gosh-wow going on, probably too much. But at the same time, I don't think it's fair to say people are shilling things they haven't worked with. Part of the problem is probably expectation. What kind of book are you looking for? If I were Dan Winkler, I'd want to see a book that went into the nitty gritty details, that really gets down and deep into the guts. Frankly, I want one of those, too. But that doesn't denigrate a book like Shafer's, which, AS AN INTRODUCTORY TEXT, does its job well. I've been using it as the "sit in my lap while I hack" book since I got it. I can find things, and I've yet to run into a problem in the book I consider a killer. Is that thoroughly studying a book? Typing in examples? Probably not, but when you look at what book reviewers are paid (and even worse, what net reviewers are paid... :->) you can't expect forty or fifty hours of work for a 700 word book review. It won't happen. That said, I also tried to point out that where this book worked best was as an introductory text and as a convenient reference. I don't try to sell it as an end-all work. Neither, as far as I can tell from my discussions with him, does Shafer. ) Mitchell says: )These first CP/M computer books where hastily written, often devoid of )substance, inaccurate, and, in most cases, just plain worthless. And the first Macintosh books were hastily written, devoid of substance, inaccurate, and in the most cases just plain worthless. Anyone remember a book called "Macintosh: Appliance of the Future"? I've got a copy. It's one of the funniest things I've ever seen in print, except perhaps for the guy who actually got a book published on 50 ways to draw a cat in MacPaint [no, I'm NOT kidding! It exists!] When word 3.0 came out, I bought a book called "Microsoft word made easy" and told folks that it was a big improvement on the manuals, but it isn't soup yet (anything is better than microsofts manuals, including a cookbook in swahili). Later, came the Cobb Group's "definitive" guide to Word 3.0, which isn't (bug it's close) and which is in constant use. )The Goodman book is a classic case of this out-the-door-quick-for-market-share )phenomena for HyperCard (published by Bantam who is a late starter in computer )books). The Shafer book (published by Sams) is a classic case of )out-the-door-quick-for-market-share for HyperTalk. Also, since HyperCard is a 'free' product, and since it is one that is passed around sans shrinkwrap, a justification can be made to have the documentation out in third party. Apple's making minimal revenue on HyperCard (software sales-wise. memory upgrades are another matter) and since lots and lots of copies are floating around, making people rely on the bundled manual would inhibit it's distribution and usefulness. This is, in my eyes, one strong reason why Apple went with the Goodman book off the top -- Atkinson's strong committment to free distribution makes lots of proprietary documentation somewhere between difficult and impossible. ) And as a HyperCard )training book, Goodman's title is not that bad. But as a HyperTalk primer, it is )the pits. And that is understandable since Goodman is not a programmer and never )admits he is one. This was, by the way, the biggest problem with his Focal Point stack. No trained programmer would have shipped it. What it does is good. What it doesn't do yet (simple things, like limit checking on input data, for one simple but critical gaff) make Focal Point look MUCH more like a prototype and a product. He even built modes into the various subsystems. sigh. )I only wish they )picked me to write it. yeah. what he said. )The first book out on HyperTalk was from Walking Shadow Press: "Programming with )HyperTalk". The Walking Shadow book is distributed by a couple guys at Apple and )to this day has no real distribution in book stores and so is not really a valid )entry (yet). Not really true. it's now out, you can get it at Computer Literacy, at Stacey's in Palo Alto, and at ComputerWare. (and in the interest of completeness, I should point out I reviewed and panned the book weeks ago, long before the Shafer book appeared. So all the reviews on the net haven't been thoughtless and glowing...) )Its also expensive )($24.95 for a book on a product that cost $49.00). On the other hand if I had to )teach HyperTalk today there is little else to choose from so I would probably )turn to this book, but create my own path for the student to follow rather than )follow its table of contents. Agreed, but computer books are expensive, and there are lots of pages here. About the best computer book price you'll see is about $16.95 these days, and it isn't out of line with other Macintosh books of the same weight. And, yeah, I turn to both Shafer and Goodman primarily for guidance when I can't figure it out for myself (whcih still happens more often than I wish...). I think Shafer is stronger at the introductory angles, I think Goodman is stronger as a reference, if you can find what you're looking for (both are somewhat weak in organization, although I'll give the edge to Shafer if you can live with a little less detail) )<unabashed plug on - skip if you don't trust me> Oh, we trust you, Mitchell! )My company is working on such a HyperTalk programming book that is combination )tutorial and reference. Our formula is not to be the first out, but to be the )best out. Great! When? )It will be reviewed by Dan Winkler. Best thing I've heard yet. )<unabashed plug off> I, for one, will look forward to it, but with some skepticism. I tend to have some problems with Waite books, because I've found many of them to be somewhat on the simplistic side. A classic case of this is "Tricks of the Unix Masters" which I found to be neither tricky or full of much in the way of secrets, but rather shallow and naive. Which just goes to show, you can't win them all.... But we can hope for the best, and the HyperTalk Bible looks like a strong contender. Actually, what I'd really like to see is a compendium of the best bits and pieces from the best HyperTalk authors on the various nets. The HyperTalk cookbook. So if you need a button that flashes twice, changes icons, and irons your shirt, you can go to chapter 12 of the cookbook and find the script. THAT would be the most useful HyperTalk book of all. descriptive, full of examples, and detailed. (After all, how many cookbooks start with "this is an egg? If you take the shell off, there's this neat stuff inside!") chuq (official curmudgeon and occasional book critic for Macintosh Horizons) Chuq Von Rospach chuq@sun.COM Delphi: CHUQ There is no reason for any individual to have a computer in their home. Ken Olson, President, Digital Equipment, 1977
mitch@well.UUCP (Mitchell Waite) (03/05/88)
In article <1208@microsoft.UUCP>, stephena@microsoft.UUCP (Stephen Arrants 3/1011) writes: >>It [manual for software] is done last and fast. > I don't think you understand the process of documentation from the inside at all. In all the companies I've worked, the docs never came "fast and last". The documentation team at Microsoft, for example, is included in product development from the start. > Sure, what do I know about documentation? But you're a lucky guy Mr. Arrants. You have not had to dirty your hands with companies that ignore documentation. But come off your tower, Microsoft is not the way it is everywhere. Sure, over the last few years they have paid a great deal of attention to documentation. I am just finishing writing a book on programming with Microsoft Quick C for Microsoft Press, and have written several others for Microsoft Press. I have had an opportunity to work with beta Quick C, watch the manuals go through there revisions, and yes I am impressed. But that is just not the way it in the vast majority of computer and software companies. Don't misread me. I admire the improvements Microsoft has made in documentation, and it would be nice if other companies followed their lead. I'm just saying that is not the way it is in the vast majority of companies. > Nope. What leaves these holes [in the documentation from software companies] are: 1. Changes to the software that can't make it into the documentation because the books are either finishing the run at the printer or that the books are in the warehouse waiting for the software to arrive for shipping. 2. Cost of Goods. If a product sells to a distributor for, say $200, COG can be 15% -- $25. That's $25 for the package, disks, disk labels, keyboard templates, collateral materials, registration card, and documentation. Let's say that the documentation itself is 10% ($20) COG. I don't think that software companies are doing too poor a job. The manuals MUST be comprehensive. Third party books rarely are. > I won't say I think you know nothing about publishing, but the holes you mention are mostly minor. The main ones are caused by the fact that manufacturers don't take responsibility to teach people how to use their products. Instead they say "Oh, you must already know how to program in C. We just tell you the "right" syntax, the limitations, and if you are lucky we'll give you an example too". The manuals cop out by only giving syntax and leaving the tutorials to other folks. Why? I think its because most manufacturers are the poorest users of their own products! Sorry, but I see it over and over. Its the ivory tower syndrome. Lets see what other people think. Yes, manuals, especially ones on complex products like languages and operating systems, have to be comprehensive. So what are we suppose to think: don't expect to learn anything from them? Certainly Microsoft offers more manual pounds per dollar than any other company. But if these manuals where such a panacea, I would not be writing this book. Mitchell Waite
mitch@well.UUCP (Mitchell Waite) (03/05/88)
> Frankly, I want one of those, too [advanced book on HyperTalk]. But that doesn't denigrate a book like Shafer's, which, AS AN INTRODUCTORY TEXT, does its job well. I've been using it as the "sit in my lap while I hack" book since I got it. I can find things, and I've yet to run into a problem in the book I consider a killer. > Judging a book being used in your "lap as you hack" is not a true measure of its effectiveness in teaching HyperTalk programming. That is what Winkler is trying to say in his message. Glib statements like this are no way to review a book. Try using it in a classs of 40 students to teach them HyperTalk and see if how good it works. Just as you claim Dan has a certain idea of what he wants, so do you. I say there is a need that is bigger than you or Dan and its what people want. Are you good at figuring that out. If so you could become very rich as an author. > )The first book out on HyperTalk was from Walking Shadow Press: "Programming with )HyperTalk". The Walking Shadow book is distributed by a couple guys at Apple and )to this day has no real distribution in book stores and so is not really a vald )entry (yet). Not really true. it's now out, you can get it at Computer Literacy, at Stacey's in Palo Alto, and at ComputerWare. > Distribution means available in all the book chains across the United States, all the bookstores, and distributors around the world. That book can't be found in those stores. > Goodman is stronger as a reference, if you can find what you're looking for > Goodman's book strong as a reference. Give me a break! Its the worse example of a reference I have ever seen. Major concepts are missing in the reference sections, there are hardly any real world examples, the organization is the pits, no bugs are mentioned, etc. > The Waite Group's "Tricks of the Unix Masters" which I found to be neither tricky or full of much in the way of secrets, but rather shallow and naive. > One man's tricks is another man's introduction. I have reviews from various magazines that say they love this book because the examples are so deep and useful. Since its selling well, and there is plenty of competion, I assume we picked just the right blend. If I am wrong, hey, go write a better book. > Actually, what I'd really like to see is a compendium of the best bits and pieces from the best HyperTalk authors on the various nets. The HyperTalk cookbook. So if you need a button that flashes twice, changes icons, and irons your shirt, you can go to chapter 12 of the cookbook and find the script. THAT would be the most useful HyperTalk book of all. descriptive, full of examples, and detailed. > Such a cookbook as you describe it would have lots of shallow examples. I think more people are interested in shortcuts, tricks, tips, utilities, things to watch out for, and mostly ways to increase the power of their programming effort. The Waite Group's Tricks of the HyperTalk Masters, which was announced on this net two months ago, will be a book like that. My Script Doctor column in HyperAge magazine is based on ideas developed for that book. Next month we'll show how to make PolyButtons (multi-sided buttons) in PURE (no xcmds up my sleeve) HyperTalk. This is a great utility for gquickly making odd shaped graphic objects to respond to mouseDowns. BTW: The HyperTalk Bible will be out in the fall of this year, Tricks of the HyperTalk Masters early 89. I know, I know, its a long time away. Thats publishing. Mitchell Waite