Help

I've picked up Wicket in Action last week and I've been reading without interrupting myself so far. So now I'm reading chapter 6 and I haven't written a single line of Wicket code. It's not the first time this happened, most of my books I've read once and never tried any of the code samples.

Last week Gavin called me and we talked about the next edition of Hibernate in Action, which actually would be the second edition of Java Persistence with Hibernate. Now that JPA2 is almost done, and the first beta release with JPA2 features of Hibernate is out, updating the text is inevitable in the near future.

What I need to decide soon is if this update is going to emphasize the tutorial aspect of the book, or if I'm going to add more reference material. I don't think that decision has much to do with the length of the book (JPwH is >900 pages). It's actually all about the code examples. Of course you can not write a 1000 page tutorial, when you pass the 200 page marker, you will have to switch from tutorial mode into reference mode.

Well, because that doesn't happen automatically, you constantly ask yourself the same question: Do readers expect code that works out-of-the-book? Are they going to write that code or copy/paste it, and then expect that it will run? Will it run within the project/product setup I've explained step-by-step up to this point?

For the first two Hibernate books I always considered the answer to that question to be: Yes, maybe the readers want to try most code examples immediately and they probably will have the book open on their desk while reading, next to the keyboard, and they will try the product you are describing in Action. That was actually what the publisher expected from an in Action series book and we had endless and exhausting discussions about it. In the end, it was a lot of work and I'm sure it's not quite perfect. At some point a tutorial approach just doesn't make sense anymore and you have to break the flow and continue with point-by-point reference material. Some readers will not be able to make that jump. The reviews of the books show that, you have a few people who haven't been able to follow the text and examples and got lost at some point. They probably expected the tutorial to continue for another 800 pages.

And here I am, asking myself if I would ever do this again and why I had so much trouble doing it before. I just realized that when I read a book, I don't try the code. I'm not a newbie and I have some Java and JEE specs/framework experience, and I think it's a waste of my time to try the Hello World example in a framework book I'm reading. I'll continue reading until I hit that barrier when it's obvious to me that I need try the code I'm reading. I'll actually not continue reading a book when all the practical details are getting in my way and I've to skip pages because they are full of trivial copy this JAR here, then edit the properties file there explanations. So I'm obviously not the target audience of my own books because they start with: This is how you create your working directory, and here is how you do that on your Windows computing machine. :)

So why can't you have both in one book? I've been paying extra attention to how other writers resolve that issue. In Wicket in Action, for example, the writers obviously do not expect the reader to stop and try the examples immediately. They do not even include the product configuration and initial setup steps in the main text and instead refer to the appendix. I'm somewhat surprised they got this past the Manning in Action guidelines, btw. ;)

I'd considered this for JPwH, moving all of the setup stuff into an appendix. Don't waste 50 pages on basic setup instructions (especially JEE vs. !JEE container) but cater to those readers who have some experience and expect to pick up new stuff quickly in a day or two, without the interruption of real world problems. As the title and subtitle are probably going to be Java Persistence with Hibernate, Second Edition, I'm not really worried about what the publisher has to say.

Still, I'm afraid we're going to have many angry newbies who expect all the setup/configuration steps in chapter 1 or 2, and if one little detail is missing, they are not going to continue reading. On the other hand, what's so bad about If you don't know how to create a directory and copy a JAR file, you need to take a break and read this appendix?

So should the next edition be more like Teach yourself Hibernate in 24 hours although your shoes have 'L' and 'R' on them or should it be The Hibernate Bible, Next Edition?

P.S. Whatever happens, the next edition of JPwH will not be 900 pages. As far as I can see, the .hbm.xml and org.hibernate.Session examples will be be removed whenever they duplicate JPA functionality, so without any other changes, that's going to be 150 pages gone already.

21 comments:
27. Sep 2009, 00:50 CET | Link
Chris Bredesen | cbredesen(AT)redhat.com
Still, I'm afraid we're going to have many angry newbies who expect all the setup/configuration steps in chapter 1 or 2, and if one little detail is missing, they are not going to continue reading.

For my money, I want deeper explanation of the concepts and processes that a tool/framework/platform enables. I expect setup instructions to be in the product manual. Hibernate is already quite good in this area so I'd welcome the removal of this cruft from the book series.

ReplyQuote
27. Sep 2009, 01:12 CET | Link

Well, that's one side of it: You will have to read the manual to actually use this code. Naturally, that makes a lot of sense because stuff like JAR dependencies, configuration properties, environment and so on can change at a moments notice and even with minor new releases of the software. So printing these instructions doesn't make much sense. But any publisher who actually cares about the contents of a book (there are many who don't even have a proofread process) will have objections if you just refer people to some external docs. The readers have to get value for their money which means no matter what they know, they should find everything they need within the book. Well, Wicket in Action makes me think that it is acceptable now to move all the newbie material into appendices...

 
27. Sep 2009, 01:14 CET | Link

I would say it depends on your target audience. My guess is those buying the Hibernate book are pretty knowledgeable and have experience with Hibernate so most wouldn't need the setup in Chpt 1 and 2. However those trying to learn Hibernate and picking up the book would probably appreciate the instructions in the Appendix. It would be nice to have both. One book like Learn Hibernate in 24 hours and the other like Java Persistence with Hibernate as more of a reference book and advance topics. I know when I was learning Hibernate the JPwH was a little overwhelming at first.

 
27. Sep 2009, 01:31 CET | Link
Rusty Wright
Would it work to split it into two books? One is reference, and the other is one of those "Recipes" books. I know that I, and my coworkers, find the Recipes books helpful.
 
27. Sep 2009, 03:08 CET | Link

Uhm, I thought that recipe books are collections of best practices and patterns, with no tutorial material at all. Some completely independent chapters that might not even have any relationship with previous chapters in the same book. I don't think that is what you mean, you probably thought about something like the A Developers Notebook series (note how these are less than 200 pages...)

 
27. Sep 2009, 13:10 CET | Link
elwis

It's of course always about the target audience. Is it a getting started with .. book or a deeper analysis for the already enlightened. However, if it is for beginners I personally Love good explanations and summaries in the end of every chapter. I have to say that Ms press black books for certifications are wonderful when it comes to quickly absorb new technology (unfortunately their technologies are not as wonderful as their books ;)

And if you start with turotial steps and suddenly start to publish only fragments, yep, I would probably be one of the angry fellows. Better to put all example code in the ned of very chapter or something like that if you don't want to put it in the text flow.

27. Sep 2009, 17:27 CET | Link
Thorsten
Chris Bredesen wrote on Sep 26, 2009 18:50:
Still, I'm afraid we're going to have many angry newbies who expect all the setup/configuration steps in chapter 1 or 2, and if one little detail is missing, they are not going to continue reading. For my money, I want deeper explanation of the concepts and processes that a tool/framework/platform enables. I expect setup instructions to be in the product manual. Hibernate is already quite good in this area so I'd welcome the removal of this cruft from the book series.

I coudn't agree more. When I buy books like this I usually HOPE there is no basic 101 stuff in it because frankly every project worth its salt should provide this kind information on their homepage or in a docs folder when you download the product. So IMHO you should be able to get it up and running from whatever documentation is provided with the products itself. Now if you want to get serious with a product and want to get some deep insights or guidance on how specific advanced features are suggested to be used etc. THEN I buy a book like this. So +1 for a bible-style version of JPwH.

 
27. Sep 2009, 18:02 CET | Link
Sanne Grinovero | sanne.grinovero(AT)gmail.com

Totally agree with Thorsten and Chris Bredesen: there are lots of quickstarters, tools and short howtos to be found on the web, buying this book from the authors means I'm searching for deep knowledge and authoritative insight. Examples about clever solutions for complex problems are welcome of course :-) May I volunteer as reviewer?

 
27. Sep 2009, 19:31 CET | Link
zqudlyba

If I want a reference material, I wouldn't buy the book. Usually, Hibernate reference material provided by Jboss for free is all I neeed.

I stopped reading Wicket in Action after chapter 2 when code examples stopped working out of the box. As a consequence, my team adopted Spring MVC instead, because they provided a Web Application Reference Implementation out of the box.

 
28. Sep 2009, 10:11 CET | Link
VitoAndolini

I suppose personally I'd prefer the setup stuff, extended code samples etc. relegated to appendices. But does it really make that much of a difference? As long as the purpose of each chapter/section/appendice are clearly noted, readers can find their way to the content they need.

Very excited to hear that a new edition will be coming - I will be a customer!

 
28. Sep 2009, 18:36 CET | Link

I really don't like configuration items to be part of the main text. They provide little value to the reader and buyer of the book. Such things are usually quickly out of date, and best put on the web for free.

Part of the reason why we could get away with that for Wicket is to cut on trees. We had to keep the book under 350 pages, so something had to be removed from the main text. The setting up your wicket application chapter became an freely available online document because of that.

Commercially it is beneficial to have such content available for free as well: it makes it easier for non-buyers to try out the examples without having to shell out $45 a priori. The hope is that folks will buy the book once they get to play with the content.

 
28. Sep 2009, 22:04 CET | Link
Andre Parodi
I agree with Martijn. Config/sample project setup is best provided on a CD or downloadable on the web.

In the book i expect to find snippets of code which cover as many different things as possible. I often find annoying when books have the trivial examples documented to death and lack the more complex real life stuff you might struggle with.

Also I read books to get in-depth knowledge from subject matter experts. If i need a sample project i can find dozens of them on the internet. But quality explanations from people who understand the subject are harder to come by.

my 2c.

 
29. Sep 2009, 10:35 CET | Link
genman

I'd like to see some counter examples. E.g. things not to do and what happens when you try. Or stuff showing it designed one way, but here's this better approach, etc.

 
30. Sep 2009, 01:58 CET | Link
Arbi Sookazian

Having thoroughly read and dog-eared my copy of JPwH over the last 2 years, I am pretty familiar with the writing style and material covered in the book. I would say that the book is too long/heavy but bearable. The Seam chapter, although an excellent intro, may be eliminated.

I would recommend splitting it into two volumes like Horstmann did for the Core Java series: http://www.horstmann.com/corejava.html.

One volume can be more beginner-oriented (what is a PersistenceContext, EntityManager, HQL/JPAQL queries, Criteria API, hbm2java tool, etc.) with tutorials.

The second volume can be performance optimizations (n plus 1 problem, cartesian product, etc.) and advanced topics like second-level cache.

I'm assuming that it will cover JPA 2.0 Criteria API so there will hopefully be no need to go back and forth b/n JPA and Hibernate versions of the API. Minimizing the references to the same or similar methods in EntityManager interface and Session interface gets confusing and disrupts the flow (esp. with the hibernate xml config files).

Looking forward to the next edition! What new topics (if any) will be covered?

 
01. Oct 2009, 00:57 CET | Link

For my two cents - if I were going to do a Hibernate book today, I'd write ALL the code examples as JUnit test cases, and I would put it all in one or more Maven project(s).

 
22. Oct 2009, 17:06 CET | Link
Senthil

I like smart books rather than more tutorial like books. All we want is real world topics, examples.

23. Oct 2009, 20:20 CET | Link

I agree with Will Iverson. Use maven...let it handle dependency resolution. I'd say use TestNG over JUnit, though ;)

I've had to learn a lot of frameworks in the last 2 years, so perhaps I am becoming a veteran, but for me, I am looking for a code sample and explanation text. I don't want much more. For example, If you're explaining @OneToMany, first show me the code, then answer 2 questions: WHAT and WHY. As briefly as you can, explain what it does in a manner in which a dumb person with ADD can understand and then devote more substantial text to why it is used and when the user wants to use it.

If users are interested in fine details, let them download the sample code. Things have changed greatly since you wrote your first Hibernate book (which lies tattered on my shelf, read through many times on my subway commute). In the old days, I started a project by having a book like yours open on my desk and copying the code. Now I download the samples.

SVN and Maven make it really easy for me to read through sample code as it's trivial to expose an SVN repo and easy for me to understand someone else's project. Sample projects are quite valuable for learning the fine details and plumbing. I personally go to books to learn the theory and to get a survey-level view of the features that are available so that I can refer to them in greater detail in the documentation later.

While I have your attention, I think one thing that is sorely missing in Hibernate is an ORM strategy, design patterns, and best practices book. It is out of scope of JPA2 in Action, but it's far more valuable to experienced programmers and I think it'll greatly help the actual technology's adoption. A lot of us know how to get things done, but aren't confident we really know what we're doing in the ORM realm.

I am a very experienced RDBMS programmer, but sometimes have difficulty figuring out how to map conventional DB designs to JPA/Hibernate. I usually figure out how to get my code working, but often wonder if it was done right or some barely passable hack. An advanced book that covers mapping strategies and RDBMS design would be a godsend if it was reasonably easy to read. I would want an advanced mapping book both to refine my knowledge and make it easier to train more junior employees. People like me normally wouldn't buy JPA2 in Action because we're experienced with Hibernate and JPA assume we could pick up the new features by reading the JBoss website. If you had a good book describing best practices and strategy, every senior programmer and developer who wants to be a senior programmer would beg their boss to expense a copy.

 
08. Feb 2010, 02:17 CET | Link

My experience with the Seam and Hibernate projects and the books on these topics can be summed up thus: exceptional projects and exceptional books - BUT - nearly impossible to get working. I consider myself quite adept at figuring out how to get things working, but with either of these projects, I come tantalizingly close to doing it but don't quite manage to in the end. Granted, these are complex projects by nature. Hibernate in Action and Java Persistence with Hibernate are eminently readable and can be understood well.

However, to really get productive, I need to be able to get the setup working quickly. Every time I have tried this, I have failed because:

  • jar dependencies are not accurately mentioned or are not easily found
  • location of the dependency documentation changes from one version to another
  • third party jar files included in the distribution are the wrong version (example slf4j with Hibernate)
  • no clear documentation anywhere indicating which Eclipse version + JBoss Tools + Seam framework combination works.

I have still not given up on getting it working because Seam has come closest to my ideals for a Java framework which I would have built myself - if I had the skills in that area :-)

You guys have done a brilliant job in designing Hibernate and Seam, and in your books you have done a terrific job of explaining the theory and rationale behind your design decisions and best practices, but I would appreciate if you could spit and polish your products to deployment perfection so guys like me with other priorities (like getting projects out the door so I can feed myself) can get on with it.

There is no one place where I can find a bunch of binaries that are guaranteed to work together. When you launch this book, If you can do ONE THING, please: freeze and make available a working set of binaries (needn't even be Maven-based, concise instructions and guaranteed-to-work links are enough) that goes with the book. If I have the book and the binaries then I can learn. Once I am familiar with the whole thing, I can then go and get the newest builds from the main download areas of the individual projects and start experimenting.

Looking forward to the new book. I would like to help or contribute in any way possible

 
09. Feb 2010, 13:51 CET | Link

In context of tools:

no clear documentation anywhere indicating which Eclipse version + JBoss Tools + Seam framework combination works.

JBoss Tools work with all Seam versions it's ever supported, so the newer version of JBoss Tools the better support. If you go to http://jboss.org/tools/download we even spell out the dependencies.

There is no one place where I can find a bunch of binaries that are guaranteed to work together.

If the above is not enough, then go look at JBoss Developer Studio - that is exactly what that product provides.

If for some reason we missed something and you found a bug/incompability then please go on our JBoss Tools forum and raise it so we become aware of it and can help.

 

--max

 
10. Apr 2010, 18:41 CET | Link

A Hibernate Bible should be neither tutorial nor reference.

Many tutorial books are really a waste of time, because they show how to solve one particular problem with one particular solution. The reader are lost, if their problems differ from the tutorial project. What's the use of a book that sets you up and running - but up and running in the completely wrong direction?

Many reference books are really a waste of time, because they show how to handle the difficulties of particular elements of the framework. But they offer no guidance to the reader which elements are appropriate in which situations.

A good book should convey as much of the author's experience as possible. It should empower the readers to come up with good solutions to their own projects. This includes good architecture. So please include why a solution works. What are the alternative solutions? Why is one solution better than the other? How are the solutions suited to solve different aspects of a problem?

I believe plain text and diagrams are better suited to convey experience than redundant sample code and screenshots.

11. Aug 2010, 19:10 CET | Link

In the Java Persistence with Hibernate book, which jar is HibernateUtil class in? Which version of hibernate 3.2.7? Or is it external to the core? Can't really do the example without it.

Post Comment