In Code in Books, Bradford talks about his frustration about source code errors within technical books.

As far as code errors in books goes this is a very trivial error. But it does point to the fact that the person who wrote the example, in this case not the primary author, didn’t even enter the code in an IDE much less compiled or tested it.

I also find this frustrating and it's up to the author to ensure that they don't make any changes to code examples after cutting and pasting them from their IDE (assuming they do this, of course).

However, as an author myself and from my own experience, it's not necessarily the author that makes these mistakes. After spending around 8 months of my own time on Professional JSP Tag Libraries (Wrox, 2002), I was pretty gutted to see that so many mistakes had crept in between the final edits I saw and the copy that went into print. These included errors in the code samples along with errors in the UML diagrams that I had put together to describe the way that the tag library APIs worked. You see, all of my diagrams were redrawn before the manuscript went into print and I didn't get to see them beforehand. UML class and activity diagrams were redrawn incorrectly with trivial mistakes such as incorrect package and method names. You can see my old errata page here.

My recommendation to anybody writing books and articles? Make sure you get to see the final final final copy of the manuscript before it goes into print. Either that or self-publish via a blog. That way, at least you know the mistakes are yours. ;-)

p.s. I'd be really interested to hear from other authors about how you manage source code examples in books, articles and presentations. Do you cut and paste it from your IDE or do you have a much more sophisticated way of linking together text and source code?

Responses[5]

Posted by Simon Brown on 03 January 2007 15:37:00 GMT #