A number of reviews have already appeared for Practical OCaml, and they have been uniformly negative.
I was involved in production as a technical reviewer. I can now say what I think about the book in as honest a way as possible. This information might be useful for people tempted to become technical reviewers for other books.
It also helps that the final cheque is winging its way to the bank as I write.
Technical reviewer
So what’s technical reviewing all about? Technical publishers employ a few technically minded editors, but these editors cannot possibly be experts in every field. So the publishers employ experts to fact-check the books during production.
The technical reviewer’s responsibilities include the basic fact-checking (like does the code run and is what he’s saying true?), but they also point out parts of the text which are unclear, and concepts which need to be covered but aren’t. It’s important to note that the job is to bring the author’s and editors’ attention to these unclear and missing sections, not to actually write them.
A technical reviewer for Apress gets to write what are described as “candid midterm assessments” about the book’s marketability.
In case you’re thinking this sounds like fun, well I guess it can be if you were the expert in charge of a classic like Programming Perl. More realistically though you’ll be ploughing through first, second and third drafts of a book you have no creative control over, pulling out the code snippets and running them, recreating the author’s development environment, fact checking every sentence, and trying to follow the reasoning from the point of view of a language beginner.
Doing the maths
For this job you will be paid $3 per page. That is, as it turns out, $3 per page published, not $3 for every draft of every page you review.
To save you rushing off to Amazon to find out what I got, I’ll tell you that the final money earned was just over $1,300. After taking into account the ruinous $-£ exchange rate and UK bank charges I’ll probably end up with £650, and after tax that will translate into about £450 spending money.
How long did it all take? In the end I reviewed 53 chapters (that is to say I reviewed some chapters more than once - there aren’t 53 chapters in the book). It takes as a rule of thumb about one hour to review each chapter, some take longer, some are quicker. Let’s say I did somewhere around 50 hours of work.
This works out at around £13/hour before tax.
That’s a snip over the average hourly wage for a UK worker (£12.50/hour according to the GMB union). It’s quite a lot less than Merjis charges out.
Early signs are discouraging
Books, though, are about love, not money. Did I love this book? Not much.
It was evident quite early that the author did not have a very natural writing style and was having trouble explaining himself on a level which would work in front of a classroom of, say, students or professional programmers.
I sent a first draft to my colleague for his assessment. He used to be a university lecturer, so he knows a thing or two about teaching new concepts to students. This was a fragment of what he wrote back:
Marred by repetitious sentence structure, poor examples and leaps in logic and category. Not the worst I’ve seen, but makes a confusing topic even more confusing. […]
I think the judgement should be that [the author is] prevented from publication until they read The Elements of Style, some [university] teaching material, and have actually tried to teach from the material.
(My emphasis). Teaching from the material is important as I found out recently when I taught a student some basic OCaml. Students find some unexpected things hard, and other things you thought would be difficult to pick up prove easy. My student had no problem whatsoever understanding the difference between [1; 2] and [1, 2] which are both valid OCaml expressions with quite different meanings. At that point half an hour or so of my teaching materials suddenly became irrelevant.
The other problem was that I am seemingly by nature very fussy when it comes to correct layout of code and code that actually works. A lot of this code was laid out very poorly, not indented correctly, and in some cases unfortunately did not work. I had the thankless task of trying to format the code to be reasonable, then track down and comment on the problems.
This was not helped by having to do all this in Microsoft Word XP, a tool that is manifestly unsuitable for this type of collaborative, precise technical work.
The candid midterm assessment
I only wrote one candid assessment, and decency and privacy prevent me from disclosing what was in it. I will just say that it was not positive.
Apress wanted to go ahead and publish. They said they would “try to make sure that the awkwardness is taken care with a heavy copy edit/dev edit”. I haven’t received a final copy of the book yet, so I cannot say whether this heavy editing was done and if it corrected the problems.
Final lessons
I suspect that I won’t be asked to do any more technical reviews for Apress books after they read this. Obviously this was a bad experience, and I’m sure some technical reviewers have a lot of fun in their work. If you are asked to do a technical review, make sure you understand that it is not an easy way to make money, and if you have doubts about the book, raise them as early as possible (I waited for much too long).
I ought to have insisted that my name didn’t appear on the book — that was a mistake.
Finally, should you buy the book? I will leave you to make up your own mind on this. Read a variety of reviews. There are several free OCaml tutorials around which you might like to look at first.
Simon P. Chappell wrote,
I feel for you. I used to do pre-press technical reviews, but they are LOTS of work and some of the publishers (Manning) don’t even pay for them anymore. You just get a copy of the book and your name on the acknowledgements.
I switched to only doing Slashdot style reviews. Much better. I still don’t get paid, but I do get a copy of the book and the opportunity to rant and rave. As I get to pick the books, I usually pick the ones that I think are going to be good. That helps the relationship with the publisher. :-)
That being said, I did request a copy of Practical OCaml, so it’ll be interesting to see whether they send it out or try to keep it low key.
Link | November 9th, 2006 at 4:18 pm
nev wrote,
I’ve done a few tech reviews One was a “Definitive Guide”-type book that was excellent; I found minor problems but in general I probably learned more about the subject than I was able to contribute.
The others were all by the same author (a native English speaker) who literally could not write a sentence. I don’t mean the style was a little awkward, or not to my personal liking; it was not at a 5th grade level. I had to be told repeatedly to ignore the grammatical problems, but it was irritating that this person was going to have their name on the cover of a book when the writing was at the level of an incoherent blog post. Subsequent drafts I received had been completely re-written, and yet this author continues to be published. I don’t understand it, as the technical competence was also rather poor.
I agree that the per-hour cost is totally not worth it, but I actually enjoy the rigor of being forced to learn the subject in depth enough to fact-check. I content myself with treating tech reviews as less a part-time job than an educational subsidy.
Link | November 9th, 2006 at 5:42 pm
Friedrich wrote,
I can follow your arguments, I remember having asked Apress what they’d think about a book “Practical C”, because of the really good “Practical Common Lisp”, IMHO this is very much needed, because of the immense number of libraries.
Well they told me that they are not interested. Now that I read this I’m quite happy that there were not. Imagine that book would be “bad” written and just to deliver something it would have been published.
But there’s one thing which really disturbs me. The publishers usually do not pay someone for the work involved while writing, but some percentage of the sellings.
So why were they forced to “publish”? And what happens now to someone with a good idea? Will they publish another “Practical” book in that series?
Will they find a better writer next time? Or don’t they care at all?
Regards
Friedrich
Link | November 11th, 2006 at 8:24 am
rich wrote,
Frederick:
I don’t know why they published the book; as I say I haven’t read the final version and it might be a substantial improvement on the drafts which I reviewed.
Link | November 11th, 2006 at 12:05 pm
Andreas wrote,
I recognize this, I did review two books for Wrox Press a couple of years ago, and they failed to pay me totally. The original text of the “meat” chapters was lousy, so I ended up re-writing some of them.
It seems some of these books are just “up for grabs” for someone who is interested in the subject, and making a name as an expert - even though they do not have any practical experience.
Many bad books out there :)
Link | November 11th, 2006 at 12:18 pm
Mark Wutka wrote,
I have done work for Que & Sams (same company - Pearson) and they have never failed to pay me. There are two ways to be paid for writing, one is on a per-chapter basis where you receive some money up-front. It might be, for example, in the neighborhood of $20 per page. The other way is where you get paid from the royalties, and you usually have to write a certain percentage of the book in order to be paid from the royalties. Typically, you are paid up-front with an advance on the royalties, and this is usually done at certain milestones in the process (1/2 done, all done, edits completed, etc.). Once the book is published, you don’t get any more money until it has earned enough royalties to cover your advance.
I am disappointed that Practical Ocaml wasn’t better. I’d love to see an Erlang book done well, too. It sounds like Rich did what he was supposed to, it is unfortunate the the publisher didn’t listen.
Link | November 12th, 2006 at 3:00 pm
Friedrich wrote,
Wow 20 $ a page that’s quite interesting. If he authors are doing as bad than me then that would be around 7 Dollar a “really” published page, well sometime I made it in less than three runs, but I always need two runs to get somewhere neas something I “can accept”. If I had the choice I’d like to the the following “hopefully good books”
- Erlang.
- Haskell
- Smalltalk
- C
- maybe Cyclone, D or something like that.
- …others ;-)
Howerver if they do pay in advance why don’t the insist on getting well written stuff delivered? And why won’t the let do proof-readings and “hear” on them. I remember that I just had comment on another book I find very valuable ‘Programming Ruby’ and I pointed out some “trouble-spots” in the Ruby-C-edge (wel it was a comment about C and the author has changed that immediatly). What do you loose if you act like that?
The longer I think about it the more strange this becomes.
Howerver maybe Peter Seibel’s way of doin such book was “wise”. AFAIKT he asked Question ins comp.lang.lisp over and over again, he put the draft out on the net and has invited all to comment on it. Common Lisp is a quite complex language and Ocaml has his share of complexity also. Maybe it would have been a good idea to put that stuff out for “public discussion also”?
It’s sad I’m looking into a good book for Ocaml since ages, the best I found was supposed to get published but it never was. I think this would have been a good thing for Ocaml. This language is really underestimated….
Have a nice day
Friedrich
Link | November 13th, 2006 at 8:03 am
Mark Wutka wrote,
Friedrich,
While they pay before the book is published, you do usually have to turn in quality chapters in order to meet your milestones. I don’t know what happened with the Practical Ocaml book, but book projects don’t seem all that different from development projects to me. How many times have you seen a finished software product and you wonder how anyone could release anything so buggy? Sometimes the deadlines are not driven by whether the code is “perfect”, but whether it beats another product to market, or whether it hits a date that was promised by marketing people with no clue how long it should really take. I suspect that something similar may have been going on with the Practical Ocaml book. I think the date slipped a number of times, so there may have been a push to get it out the door. It is also possible the publisher was unable to find anyone to fix what was wrong, or they may have decided that it was cheaper to just publish what they have rather than fix it.
I like the public discussion model, and maybe that would have helped, but many times, the publishers are trying to hit specific dates and the public discussion model is too slow. Computer book publishing is pretty kooky - the publishers are often trying to please large-scale book-buyers (bookstores) and not necessarily individuals. In theory, the book-buyers should be paying attention to what people want.
Maybe someone could start a public-discussion Ocaml book and then just make it available through a print-on-demand publisher like lulu.com. I wonder how well that would do. Does anyone know if a model like that has worked well before?
Mark
Link | November 13th, 2006 at 2:39 pm
Scott Walters wrote,
Hi,
Tell it, brother!
I just requested two review copies of this, not bothering to have read any reviews first. I guess I didn’t want to be biased, but the friend who I requested another copy for sent me here. Now I know why APress didn’t respond. (I requested some books from ORA at the same time and got an immediate reply, though the receptionstic person took seriously my mini-proposal for Perl Flowchating and couldn’t remember if _Learning Haskell_ was a O’Reilly title or not. Usually ORA’s entire staff is sharp as a tack. Didn’t mean to screw with the innocets. Not all of us have had apple pie made from the tree of knowledge of good and evil. Anywho.
Just wanted to empahtise. I did technical review for _Perl: How to Program_. The author-bots cut and paste their VB book and then edited it and rewrote the examples. Perl is written in a radically different style — when it’s written worth a damn — so the coverage was abysmal. The code was littered with style problems, security problems, and downright ignorance, none of which would be corrected before it went to print. And in 800 pages of rubbish, they didn’t scratch the surface of programming or Perl. Worst of all, the goons who wrote this apparently were calculated about doing little work, churning out books, and making money. They have the market virtually corned on massive introduction volumes.
Sad to hear about APress. I’ll be interested to know who the editor was that signed this deal. I wrote for them. They had to pry the content out of my hands. Some chapters got rewritten ten times. I’m still not happy with it. Copy edit butchered it a bit. Microsoft Word was a pain (though wine ran it admirably). I wrote the thing in POD and wrote some code to compile the POD into RTF — and not just plain RTF, RTF that passed for the output of Microsoft Word’s RTF, which was littered wih bizarre style crap. Microsoft is not the tool for that. O’Reilly is doing DocBook, and their authors use a mix of technical tools. I originally pushed ORA to take TeX, figuring they’d be unable to refuse and I could generate it easy, or learn LaTeX, or the whole experience would be a net positive. But aside from dealing with Microsoft Word, the experience was positive. They were supportive of my repeated schedule slips , I expect because they saw work in (though they took inventory of what I had more and more frequently). My editor had good feedback, and I was involved (to various degrees) in various parts of the process. At one point, I was arguing cover price with higher-ups, and even though the copy text went back and forth several times, I was still allowed togive final approval on what was actually used. It was a good experience. I guess I hate to see them for want of a dedicated author, and some dedication on the author’s part (especially when it comes to technical review’s input) would have made it at least an average book. I’m convinced that Perl owes its success largely to the quality of certain books written for it, including the original Programming Perl you mentioned. Larry’s carefree style puts readers at ease while he delves into things that would otherwise be fussy sounding details or stress-inducing advanced topics. The flip side of the coin is that a language without good reading material is at a serious disadvantage. I *want* to learn OCaml. My friend wants me to. I guess Mozilla needs to do a lot better job keeping place in electronic documents.
-scott
Link | November 14th, 2006 at 3:22 pm
Marek Kubica wrote,
Well, the upcoming Django book which will be published by Apress is under public review now, you can find the published chapters on http://www.djangobook.com . As you can see, there are a lots of comments about the book and a really easy possibility to comment, so I hope the authers will take care of the comments and incorporate them in the final version of the book which will go in print.
Link | November 19th, 2006 at 2:30 pm
Al Hoang » Reviews on Practical Ocaml wrote,
[…] Ehud comments: I haven’t seen the book yet, but it’s really sad if the book is as problematic as this thread indicates. I had high hopes for the “Practical X” line of books. I thought it might become an O’reilly-like brand for books about non-mainstream language Matt comments : This book is a big disappointment. As already noted, it has some severe stylistic problems and the writing is uninspiring, to say the least. But by far the worst problem is that the author’s knowledge of his subject is simply insufficient. This shows up all over the place, but I’ll highlight two examples that I think exemplify the issue. William comments : Some items are given only a superficial introduction (e.g. variants — a very important part of OCaml), and then used fairly heavily two chapters later without so much as a pointer back to their introduction for people skimming the book. and finally Merjis (one of the technical reviewers) writes on his blog : I only wrote one candid assessment, and decency and privacy prevent me from disclosing what was in it. I will just say that it was not positive. […]
Link | November 20th, 2006 at 5:31 am