I use this blog as a soap box to preach (ahem... to talk :-) about subjects that interest me.

Wednesday, October 31, 2012

Authors' Mistakes #4 - Vince Flynn

Well, this is not really a mistake, but bad writing. Not something you would expect in a “New York Times No.1 Bestseller”. The book is “Extreme Measures”, and the problem is on the first page of Chapter 39.

Vince Flynn writes: In many ways it was what made him such a great leader, but his lack of trust and inflexibility had also made things almost impossible.

Since when is lack of inflexibility counterproductive?

Clearly, lack should be read as referring to trust only, not to trust and inflexibility, but the sentence is ambiguous and, as such, unacceptable.

To fix it, he would have only needed to swap the two shortcomings and write his inflexibility and lack of trust. Surprisingly, no copy editor picked it up...

Sunday, October 14, 2012

JSP, JSF and Tomcat Web Development

Apress of Berkeley (CA) has released the second edition of my book Beginning JSP, JSF and Tomcat Java Web Development.

The first edition of this book was released in November 2007.

Some years later, Apress asked me whether I would have liked to write a second edition of the book.  My reply was that not enough had changed to warrant an update.

Then, in early 2012, they asked me again. In the meanwhile, JSF had added three new libraries of elements and Java 7 SE had been released.  Michael Sekler, who had contributed to the first edition, agreed that I would go alone with the second edition.

I said yes.

It took me five months to change the structure of the first edition, update and add functionality and examples, etc., but it was worthwhile.

You might be wondering why it took so long.  After all, most of the material for the second edition came from the first one, right?  Not really. The problem with writing computer books is that you cannot simply write your stuff and be done with it. You have to write examples for most of what you say, and this adds a whole new dimension to writing. You have to write the examples in the tightest possible way, because thousands of smart people will pore over them.  No slacking off in either format or content. Not even one superfluous or missing tab.

And then, once you have designed and written your examples, you have to test them in the most thorough way.  This also applies to the examples you have from a previous edition.  You see, in computing everything keeps changing. Therefore, one example that was working flawlessly a couple of years ago, even if it doesn't fail (thanks to back compatibility), it will generate a lot of warning
messages during compilation. And a professional developer doesn't want his/her code even to generate a single warning!

For web applications, you have to test your examples with all major web browsers (Internet Explorer, Google Chrome, Firefox, and Opera).  This often leads to changes that have to be retested again from scratch.

Once you are happy with your examples, you need to integrate them into the text of the book and explain them in enough detail for the reader to make full sense of them.  And sometimes the lines of code don't fit into the printed page...

And don't think that the work is done once you send the chapter off to the publisher, because technical and scientific books are different from novels and most non-fiction books: before going through copy-edit, they are technically reviewed.  And although if you have been exemplary with your coding, debugging, and documenting, the TR (Technical Reviewer) might come up with points you had not considered, or points you had considered and discarded without mentioning them in the chapter.  Even if you avoid having to rework the examples, you will have at the very least to explain your choices...

One of the readers of the first edition complained that it contained not enough material on JSF. In this second edition I did something about it: in the first edition, I had devoted to JSF a chapter plus a quick-reference appendix; in the new edition, I dropped the quick reference and added a second chapter to the main body of the book. By doing so, I added quite a bit of practical information on JSF, because much of the quick reference appendix consisted of a list of elements that you can already find explained in several web sites.

Another complaint about the first edition was that it included too many appendices and too much extraneous material. Well, there were as many appendices as chapters! I had done it for two main reasons: I wanted to keep the main body of the book uncluttered but I still wanted to provide information on everything needed to write a dynamic web page. The resulting table of contents was as follows:

CHAPTER 1 Introducing JavaServer Pages and Tomcat
CHAPTER 2 JSP Explained
CHAPTER 3 The Web Page
CHAPTER 4 Databases
CHAPTER 5 At Face Value (JSF Primer)
CHAPTER 6 Communicating with XML
CHAPTER 7 Tomcat 6
APPENDIX A Installing Everything
APPENDIX E SQL Quick Reference
APPENDIX F JSF Quick Reference
APPENDIX H Abbreviations and Acronyms

And here is the new table of contents:

CHAPTER 1 Introducing JSP and Tomcat
CHAPTER 2 JSP Elements
CHAPTER 3 JSP Application Architectures
CHAPTER 4 JSP in Action
CHAPTER 6 JSP and Databases
CHAPTER 8 JSF and eshop
CHAPTER 9 Tomcat 7
CHAPTER 10 Eshop
APPENDIX C Abbreviations and Acronyms

I eliminated the appendices on JSP, JSF, and Eclipse by merging their contents into the main body of the book. Then, I made the appendix on package installation disappear by explaining how to install all necessary packages as they became necessary. Finally, I dropped the appendix on HTML characters and told everything I wanted to say about HTML and SQL in the two remaining appendices. The result is a much better book in which the chapters are clearly focussed and that you can read with less flipping forth and back.

What are you waiting for? Buy it!