Friday, May 07, 2010

Do NOT write books this way! "Wicket in Action" case.

Copyright (c)
I've been just reading quite a good book on Apache Wicket from Martijn Dashorst and Eelco Hillenius and I got really pissed off at some point. I've always loved "... in Action" series because of its language, attitude to teaching the subject and quality of the material. I've had the same feelings with current book i.e. "Wicket in Action" until page 219 where authors were presenting advanced custom component creation and under one of the listings they wrote: "an elaborate explanation of it (the listing) is outside the scope of this book". WTF?

How can a writer put something like this in his book? If you think the example is too difficult for the scope of current book don't show it at all! You could also redirect readers to the other resources like: "detailed explanation of this concept can be found at ...". But writing "an elaborate explanation of it is outside the scope of this book" is just stupid and frivolous! I pay for the book to have explanations of difficult and complicated subjects - not to read that it's out of the scope (show external resources!).

Anyway, the book is quite good, but more and more examples in the second half of it are getting blur and need more explanations (maybe better metaphor than a bit artificial "lasagne"?)

I hope the authors will make an effort and upgrade the content of this book to the newest Wicket release 1.4.x that introduced Java generics and refactored many classes (e.g. validators).


Helen Neely said...

I totally share your frustration with this book. In fact, it looks like this is a common practice with Manning authors. I too recently bought a copy of The Quick Python Book and was very angry at how many code sample and design decision were not explained.

I've giving up on Manning books; they're all crap.

nico said...

i read that book and it is great, the example is good and the explanation of the components too.
The book has the minimum to start in wicket, and explanation of the core, components, layout, i18n, forms, validation, Models, url coding, resources, etc.
Wicket framework is really big, if you need to write all in detail, it would be a 1000 pages book.
The only thing wrong i can say about that book, is that is not update with the new release of wicket.

Anonymous said...

I also read the book. What I'm missing in it is info about the lifecycle of a Wicket app and requests.
Something that is very important in complex web frameworks like this.

Anonymous said...

Unless you're willing to pay for 1000+ page books, you're going to find a *lot* of stuff is out-of-scope.

Be realistic. Book authors make pennies per hour writing low-volume tech books.

You want more documentation on that stuff? Write a blog post instead of complaining about it, or write your own book. It's a non-trivial undertaking, and there's not enough time, not enough room, not enough reward, etc. to put in everything *you* think should be in.