How Not To Write a Technical Book

The 5th rule…

Great coding ability doth not make great authoring ability…

Interesting that someone cited the Amazon comments on C++ How to Program. I wrote a review there, and I hated the color in that book. Not because it was in color, but because the little tips, warnings, hints, etc. broke up the text to the point it wasn’t readable.

On the other hand, I have a copy of WPF Unleashed and I think it’s a fantastic book. Lots of clear examples, and an arrangement that, for the most part, makes it easy to skip around and read the parts you want to focus on.

Is anyone else disturbed, though, by the fact that a full-color book sells for the same price as a typical black-and-white computer book? I knew these computer books were surely way overpriced, but now we have clear confirmation. Anybody happen to know just how much color printing adds to the cost of a book?

Certainly writing is first and foremost, but layout actually has more than just aesthetic value.

Read the intro to any of the Head First books and you’ll learn that they’re layouts are not just inspired by whimsy, but by research into how people absorb information.

With long unbroken blocks of text, readers only remember the first and last sections. By breaking it up into bites, and with little sidebars etc… that reinforce the main content, readers retain more information.

I agree that Nathan’s book looks better in this context, but this is a snippet, so it might not be a completely fair comparison for the works on a whole.

With that said, I would get Nathan’s book anyway. He did a terrific job on his COM and .NET Interoperability book. I am sorta surprised you did not recognize him.

I wholehearted agree with Jeff about these two books. Adam Nathan’s book was a joy to read and a valuable resource to get up to speed and understand WPF. I read it twice now and still go back to it for the “digging deeper” sections and to drill into details on specific topics.

I read the first 3 chapters of Petzold’s book, chapter 19, and a few other chapters where the XAML part starts. The reading was tedious and the knowledge was not immediately usable. I didn’t know what to expect with the code samples as there were barely any screenshots to illustrate the code. The part I also didn’t like sometimes it’s hard to just use the index and look up something and understand it as the chapters refer back to other previous chapters.

After working with WPF for awhile now, Petzold’s book is way more clear. I still refer to it occasionally when I run into a problem programmatically doing something in WPF. Most of the time I stick with working declaratively in XAML. For a beginner I would definately recommend Nathan’s book over Petzold’s.

Apparently there’s sanity in the madness. Petzold blogged a lengthy post about why he structured the book the way he did http://www.charlespetzold.com/blog/2007/03/050139.html . The last 3 paragraphs are the most relevant to this topic. My emphasis added:

“If I had to write the book all over again, I’d do a few things differently: I’d definitely put a bunch of screen shots in the book. NOT DOING SCREEN SHOTS WAS A MISTAKE. …

Reading a thousand-page book all the way through requires a big commitment and a lot of trust in the author. “If I devote the time, will the author deliver the goods?” My book was not written for reference or for skipping around. IT IS A COMPLETE TUTORIAL INTENDED TO BE READ FROM BEGINNING TO END, and if my decisions seem perverse (“Chapter 2 covers brushes???”), rest assured that my choices were not arbitrary, but instead the result of dedicated thought and consideration. I know what I’m doing. I’ve been writing books like this for 20 years.

Applications = Code + Markup is hardcore: It’s for programmers who seriously want to learn the intrastructure and application of WPF — both in code and XAML. “

It’s funny that you only link to Petzold’s wikipedia page because Nathan (“some guy you’ve probably never heard of”) is on wikipedia too! Although not as well known as Petzold, we already knew him from his .NET and COM book and the pinvoke.net website. I agree with you 1000% on the WPF books. I wasn’t surprised though. To the commenter Will: I think it’s weird to make generalizations about books based on the publisher (like Sams). I think 90% of a book’s worth comes down to the author.

I don’t really understand why anyone would even want to buy a programming book. No way to run the example code (without finding it online or on some attached CD/DVD), no way to copy and paste, no way to click a link to a different topic, the trusty web browser with Google bookmarked to look up terms or expressions you don’t know is far away. It’s like living in the dark ages again.

Twisti, I totally agree-- the idea that books are competing with other books is an illusion. Books are competing with the web. And the Adam Nathan book does a surprisingly good job of it.

To anybody complaining about the color…don’t you have color syntax highlighting in Studio?

It’s funny, I’m having the exact same issue right now with a textbook on programming languages:

http://www.amazon.com/Concepts-Programming-Languages-Robert-Sebesta/dp/0321193628

…the author’s idea of visually delimiting code snippets is…uhhh…oh wait. He doesn’t. The only visual cue he gives readers is indenting and whitespace, and maybe more frequent italics/bolds. Other than that, he doesn’t even have the decency to change fonts or not be a cheap ass and go for color. The entire book is like staring at a newspaper for three and a half months, except with no Sunday comics.

I also can’t stand the the separation of subjects within chapters; the headers aren’t distinguishing enough to let you know you’re changing subjects, or still talking about the same subject. The difference between header sizes doesn’t give the reader appropriate visual cue to let them know that we’re moving on to a new subject.

Don’t even get me started on the lack of meaningful diagrams/illustrations. All in all, it’s very useful, intelligent material that has been conveyed in the crudest possible way. I’m glad I purchased the 6th edition for $13 instead of the 7th edition (which is almost identical) for $106.

How about Wrox? I have the impression that Wrox isn’t so bad. Have learned with some of their books and there are plenty of diagrams (but no color)

Maybe all us blog readers and writers just have short attention spans and have forgotten how to read a real book.

“I think 90% of a book’s worth comes down to the author.”

I would agree. However publishers make huge difference you can see that by grabbing books from the same author but different publishers. Look at most of the comments here on the Petzold book, almost all say that the information is excelling but the layout and presentation needs work. So in a choice between two books, that I have no reviews on, I am going to grab the publisher that has a good history of producing excellent books, because even if that author is poor the editor is going to increase whatever value I will get from the book.

Since this blog doesn’t allow html in comments, I will point you to http://radar.oreilly.com/archives/2007/04/books_like_blog.html, Nat Torkington’s reflections on this blog post.

I also thought I’d post in the comments on that post the sales graphs from bookscan, showing how the Nathan book is pulling away from Petzold in sales to boot.

Jeff, I’d happily provide you a pre-release soft copy of our 2ed WPF book if you’d like to add it to your list of comparisons. Just drop me a line and I’ll send it to you: csells@sellsbrothers.com.

“I also thought I’d post in the comments on that post the sales graphs from bookscan, showing how the Nathan book is pulling away from Petzold in sales to boot.”

Tim, please do.

Interestingly enough, Petzold responds on his blog: http://www.charlespetzold.com/blog/2007/04/270433.html

I think he’s a bit off base with his response:
http://haacked.com/archive/2007/04/27/prose-is-dead.-long-live-prose.aspx

I have both books and Petzold’s book actually made me loose interest in WPF. It’s just depressing to read that thing. Nathan’s book is great.

Petzold criticizes your review of Nathan’s book here:

http://www.charlespetzold.com/blog/2007/04/270433.html

I have read both books and Nathan’s is in another league both on presentation AND content. Even if he had it all in black and white, Nathan’s book is far superior to Petzold’s in every way. I would put this comment on Petzold’s blog but he doesn’t allow comments (very weak Charles).

Wow. I recently bought the Petzold book and after the first few chapters decided that it was one of the best technical books that I have read in years. So many books read like a catalog of features with a few hints and tips thrown in to add value. I think so many authors add the sidebars, faqs, warnings, etc because they do not have the literary ability to integrate the information into the main text of the book.
Petzold’s book reads like a story, it starts with the basics, but in no way treats the reader like an idiot, and it builds on the story with a gradual accumulation of knowledge.
I admit that reading the book takes a commitment and a level of trust in the author as it is long and obviously not every topic is of interest to every person. However, this is the first book I have read in a long time that I want to continue reading because it is enjoyable. So many books I force my way through the pages because I am trying to understand the topic.
I am glad that there are no pictures included because it has encouraged me to actually type in some of the programs to see the results for myself. It is amazing the increased understanding you can get from just typing in the code, over scanning the code mentally. I always find there are bits that I missed.
I think the depth of understanding that this book is able to convey to its reader is far beyond that of your average technical book. Scanning the book just really does not do the text justice. Seeing two pages of text on padding, margins and alignment of buttons, on the surface is not very sexy, but when you have spent hours in winforms trying to get controls to layout precisely, a clear and precise description of the WPF behaviour is a godsend.
So many books today are written by technology specialists who become technical writers. My opinion is that Petzold is an author who understands the technology. For me that distinction is important.

Personally I think the book is an excellent resource, but you have to make an effort to get the reward from it. This is not a teach yourself WPF in 24 hours type of book.

Took me a few days to get back to this, but I wanted to share this link from A List Apart, on the topic of contrast, which seems to be right on the spot with the examples Jeff brings up here.

http://alistapart.com/articles/contrastandmeaning

/cheer,
F.O.R.