In the Spotlight - Brian Goetz

This surprised the heck out of me.�� We recently finished a new TV room down in the basement.�� We have a 50″ plasma TV, mounted on the wall with an Omnimount UCL mount (quite an impressive bit of engineering — not cheap, but highly recommended.)�� Since the mount weighs upwards of 40 pounds, and supports a TV that weights 100 pounds on a torque arm as long as 2ft, it needs to be anchored pretty solidly to the wall.�� It is held up with 6 4″ long, 3/8″ wide lag screws, that screw into two separate studs.�� It does its job well.

So, my dad and I went to remove it from the wall.�� I removed the six screws, and we prepared to catch the mount.�� It didn’t fall off the wall.�� We tugged on it, and it still didn’t come off the wall.�� Seemed stuck so tight we thought we’d missed a screw!�� But we convinced ourselves there were no more screws, and the two of us pulled hard, and eventually it came off the wall — taking some of the wallboard with it.�� Apparently the pressure of being screwed up against the wallboard (and maybe the heat from the TV too over a few years)��turned the painted surface into a glue not only strong enough to hold a 40lb mount to a vertical wall but resist being pulled off!��

At the “Writing the Next Great Java Book” BOF at JavaOne, there were unfortunately many more questions than we had time to answer.�� Fortunately, Greg Doench saved the questions (presciently, they were submitted on paper), so I’ll answer a few here.��

Q: About how much time did you put into your book (effort, not duration)?��
A: In my case, the answers for effort and duration are the same, as I had the luxury of writing the book mostly-full-time — I made the book my foreground activity, though I still did some consulting and training while I was working on it.�� I spent approximately 16 months on the book — longer than planned (but in hindsight is no surprise.)��

Q: Was the financial compensation worthwhile?
A: Unless your name is Stephen King or JK Rowling, writing books is not something you do for the financial compensation.�� This is more true for technical books, because (a) the audience for books like Java Concurrency in Practice is not quite as large as the audience for Harry Potter, and (b) if you have the skills to write a good technical book you probably have the skills to get a well-paying technical job.�� Without going into the details, I’ll say that the compensation is about what I expected — but I went into it with very realistic expectations.�� The compensation comes in other forms.��

Q: How much support and assistance was provided by the publisher?
A: I think this is a matter of how much support and assistance you ask of the publisher — and how much the publisher thinks you need.�� In our case, we did everything ourselves, including typesetting and managing the review, copy editing, and index creation.�� These are things the publisher often does for authors (and might even have preferred to do), but we chose to do it ourselves, and the publisher agreed.�� Of course, this was more work, but it was work we gladly did.�� The A-W team was always responsive when we did ask for things.�� So I think the answer is “as much as you appear to need.”

Q: How does the short half-life of technical topics affect the effort?
A: I deliberately chose a topic with a longer half-life.�� This gave me the latitude to let the book tell me when it was done, rather than the schedule.�� For material with a shorter shelf life, I might be inclined to choose a shorter format, so that the book is less out-of-date by the time it is published.��

Q: What would you say about books that authors release chapters to the public as they write?
A: I think this presupposes a style of writing where the author sits down and writes the book linearly.�� I am sure some authors do this, and some topics are more amenable to this approach than others.�� But one of the most important freedoms in writing is the freedom to refactor continuously; very often you don’t figure out the right way to present the material until you’ve presented it the wrong way (just as with code.)�� There’s nothing wrong with putting the work out there early — this is a great source of free review — but you have to be careful that doing so doesn’t cause you to settle into the belief that the structure of the book has been decided.�� (The same risk is true of trying to adhere to a schedule that assigns due dates to specific chapters.)��

Q: How do you avoid example source code exploding without using unrealistic examples?
A: This is really hard!�� But its really important.�� In JCiP, we set a rule for ourselves of “no code example more than��a page”, with the target of making most of them a half page or less.�� This is not easy, especially in Java! (There was only one we had to break into two separate one-page listings.)�� We wanted the examples to each illustrate a single point, so that the reader could look at the example and easily see what it was trying to show.�� There are some obvious tricks; eliminating boilerplate code like constructors, getters, and setters helps a little bit.�� What worked for us was to pick realistic examples that the audience would immediately understand the utility of (such as a file crawler), but abstract away the irrelevant concrete details by not showing the bodies of methods that are not needed to make the point that the example is supposed to illustrate.�� For example, we have a set of examples in Chapter 8 where we illustrate searching for solutions to a class of puzzles such as the “sliding block puzzles.”�� But rather than focus on a specific puzzle — which would take lots of space and not offer all that much insight, we abstract the nature of the puzzle by defining an interface that specifies the initial position (in terms of an abstract Position class), valid moves (in terms of an abstract Move class), and the goal position.�� Then we can illustrates various search techniques in terms of the abstract puzzle without getting bogged down in the details.��

Q:��What would you say is the role of technical books in the age where the Internet is the fastest way to publish texts and technology changes so fast that one year after publishing texts become irrelevant?
A: Some technical books are simply a form of documentation; any book that has a version number in the title is likely to fall into this category.�� These books have a very short shelf life.�� Other books, those that tend to focus on concepts rather that specific technical details, tend to have a longer shelf life.���� In any case, the publishing industry needs to become more agile in its approach to managing the authoring and production process, and explore more seriously alternate publication vectors such as electronic publishing.��

More later.��

At JavaOne this month, my publisher at Pearson, Greg Doench, hosted a panel/BOF entitled “Writing the Next Great Java Book.” Not surprisingly, when you get four authors in a room, you get seven opinions about what’s important in writing a book!

One thing that we (mostly Tim, actually) did for JCiP was set up an infrastructure for the book, similar to what you’d do for a software project. Version control, issue tracking, one-step build script, continuous build — all of these things offer the same benefits to book projects as they do for software.

One critical aspect of the build is the handling of program listings. It is incredibly tempting to cut and paste examples from the IDE into whatever source format you’re writing in (Word, Frame, LaTeX, DocBook), but this is a recipe for disaster — errors will invariably creep in as you try and make small tweaks (such as changing variable names) outside the IDE. And code examples with errors really undermine the reader’s confidence (or worse, they copy the incorrect example into their code.) So, we wanted to make sure that every code example compiled (and ideally, was tested.)

Our approach was to check the code into Subversion with the rest of the book artifacts, ensure that the build process compiled the code and ran the unit tests, and then automatically extract the examples from the code in a format into which they could be directly included by the build. Some systems (LaTeX, DocBook) make this sort of inclusion easier than others.

We marked the examples up with comments for formatting (bold, italic) and also with “snip here” comments that excluded the irrelevant portions of the code from the listings that actually went into the book. The attached perl script (phragmite.pl), written by Tim Peierls (based on an approach designed by Ken Arnold), takes as input a set of input files and produces a set of LaTeX files representing the extracted listings.

As an example, here is the Counter listing from Listing 4.1 of JCiP:

// !! Counter Simple thread-safe counter using the Java monitor pattern
// vv Counter
@ThreadSafe
public final class Counter {
  /*[*/@GuardedBy("this")/*]*/ private long value = 0;
  public /*[*/synchronized/*]*/ long getValue() {
    return value;
  }
  public /*[*/synchronized/*]*/ long increment() {
    if (value == Long.MAX_VALUE)
      throw new IllegalStateException(”counter overflow”);
    return ++value;
  }
}
// ^^ Counter

The first line identifies the type of the code fragment (!! for a “good example”, ?? for a “bad example” which would get decorated with a Mr. Yuk), the name of the fragment (Counter), and the listing caption. The lines with the ^^ and vv mean “snip from here to here”, and a listing can be made of multiple such fragments. The /*[*/ and /*]*/ comments mean “bold”. The following ANT target ran the script:

  <target name="listings">
    <exec dir="${bin.dir}" executable="perl">
      <arg value="${phragmite.pl}"/>
      <arg value="${listings.dir}"/>
      <arg value="${fragments.dir}/*.java"/>
      <arg value="${fragments.dir}/jcip/*.java"/>
    </exec>
  </target>

In the book’s LaTeX source, we use the following LaTeX macro to pull the listing in:

\newcommand{\JavaListing}[1]{\input{listings/#1}%

Apparently, WordPress is vulnerable to some script injection bugs, and this site was hit by them.�� And Google tagged the site as “spreading malware”, so the site shows up with a warning in Google search results and FF3 users can’t get to it at all.�� I’ve upgraded Wordpress, scoured the DB for injected scripts, and am in the process of begging google to let me off the blacklist.

What a pain in the butt.�� People suck.��

I noticed this amusing typo at the trade show floor at SDWest this year.�� My first thought: wow, they really are tailored!

��