How Not To Write a Technical Book

If I told you to choose between two technical books, one by renowned Windows author Charles Petzold, and another by some guy you've probably never heard of, which one would you pick?


This is a companion discussion topic for the original blog entry at: http://www.codinghorror.com/blog/2007/04/how-not-to-write-a-technical-book.html

I read this blog and immediately went out and bought the book you recommended. “WPF unleashed” and I love it thus far. I didn’t realize color code in a book was that much more interesting to read. Thanx for the heads up!

Try reading the Expression Blend documentation. That’s what I did after slogging half-way through the Petzold book, playing with the samples along the way. Petzold was an informative but tedious experience. The Blend documentation is a surprisingly well-written intro to WPF concepts with the instant gratification of playing with them in Blend without having to write code. Petzold builds character, Blend builds cool apps, fast. :slight_smile:

Which book would I pick?

If the publisher was O’Reilly then would probably go with the O’Reilly book. Even though the book author and coverag of the topic may be bad the editing by O’reilly really bumps it up a bunch of notches.

Other the side I would advoid any of the Unleashed or anything from Sams publishing. It use to be that Sams was the tech book company, really dating myself here, but a good decade ago they became trash. Poor writing,editing and layout not to mention to many times bitten by following code in thier books and finding it was filled with problems and bad practices.
If Sams has decided to turn itself around I may have to take a look at them; or is this book just an exception?

I understand Jeff’s enthusiasm for Nathan’s book, but to be frank, I think both layouts have their problems. My first impression when seeing Nathan’s excerpts was confusion from all the colors, different fonts, etc. The text seems to dance in front of my eyes, which is not what I expect from it.

I would say that a moderate use of black-and-white syntax highlighting and a slightly slower dynamic of the text would be a better solution. Somewhere in between.

Cheers,

Carl

I read the excerpt from Charles’ book and I’m disappointed.

For example, he goes through explaining basic concepts such as the Application and Form object, and talks about the Run() function, but doesn’t illustrate it properly for the reader. His explanations are confusing, oddly-worded, and can be considered downright wrong unless you actually know what he’s talking about.

If this book is for intermediate or advanced developers, why is he explaining basics such as “static” or “Application.Run()”? And if this book is for beginners, why does he not delve into greater detail about these things if he’s mentioning them at all?

Continuing on the example of Application.Run(), his explanation makes it sound almost as if it did nothing but call the Show() function of the form, but we all know it does way more than that. It starts the message pump, spawns and executes the the UI thread, creates the application domain, etc (and not necessarily in that order).

Anyway, I think one of the reviews of the book on the Amazon.com site is pretty accurate. It’s like a wall of text with no organization and confusing methodology. Like, who binds events in the Main() function of a program?

I’m not sure someone of Petzold’s disposition (of disliking IDEs and mixing in layout code with the actual program) should be writing books on UI design and proper coding practices. Advocates of “pixel tweaking” – ie, tweaking the “new Point(34,50)” for button positions in manually generated layout code – should not be writing books on UI design either.

Just my two cents anyway.

Take care,
Sam

Take a look at the “Head First” series of books. I recently read the excellent “Head First Design Patterns” and I can honestly say it was one of the few technical books I have enjoyed reading.

They use a variety of techniques, including bold layouts, pictures, cartoons and conversational-style writing. It all seems a little silly at first, but once you start reading you realise how much easier it is to take in when compared to a dense, serious block of text.

But it’s not a “For Dummies” approach: despite the “fun” style they do cover the topic to a good technical depth.

I have recently been reading this charming little book, Concurrent Systems, An Integrated Approach to Operating Systems, Distributed Systems and Databases. See - http://www.amazon.com/Concurrent-Systems-Integrated-Operating-Distributed/dp/0201177676

The presentation of a book is key to unlocking the information inside, this book is the proof for me. Jean Bacon knows her onions and the book is full of excellent information but it’s taken me quiet a while to get to it through the tangents, wild cross referencing to bits further on, wildly abstract diagrams and the ‘why use one word when 178 will do the trick’ approach. Already a fairly dry subject this book adds silica gel…

Thanks for the excellent blog.

Professional technical writers use a combination of active-voice writing and visual layout to facilitate the efficient identification and transfer of information. That is to say that a consistent set of visual cues enable a reader to more readily identify a particular type of information.

These cues are sometimes referred to as the CRAP rule: Contrast, Repetition, Alignment, Position. (This particular mnemonic shortcut was popularized by Robing Williams’ “The Non-Designers Design Book”).

Having said that, I’d probably indent the body content a bit, leaving the headings to protrude a bit to the left. This would provide an even easier set of visual “ladders” for a reader searching for a particular piece of information.

Finally, a sound document design strategy is too seldom embraced by the online world. There seems to be some unwritten rule that an easily apprehendable visual layout makes a Web page boring…

I’m not trolling, but to me Petzolds book seems to be laid in the exact same way as Code Complete by Steve Connell.

Would you have the same problem with CC2e Jeff?

The passage from Petzold lacks focus and organization. He seems to jump from one topic to another willy-nilly. It makes it very hard to extract actual useful information.

I agree that Petzold’s book is a difficult and challenging read, but having pushed myself about 1/3 into it, and I will soon be revising that read to experiment with the samples, I must say it has provided a very good insight into WPF for an advanced developer.

I think his ‘beginner’ treatment of Application.Run etc. is for advanced programmers but Windows beginners.

I bought Nathan’s book a few weeks back, the use of colour to more clearly define the content was the first that I noticed.

I hope that more technical books follow this route as it I find it much easier to pick through and read.

Adam Nathan’s earlier book .NET and COM, was by far the most reliable book on the subject. I am not suprised that his WPF book is excellent as well.

Uh Sams is not trash, check out Stephen Prata’s C++ Primer 5th ed, very well written, great examples, the best C++ book I’ve found yet.

And I totally disagree with anyone that says programming books are not good. Having to type the code out yourself (over copying and pasting from the net), puts it into your head much quicker.

Without questioning Mr. Petzold’s reputation or expertise, I’ll have to say I was very disappointed with his books in the past (I have not read Code though.) The previous “Programming Windows with C#” seemed to me like a boring alternation between almost useless raw GDI+ tricks and trivial coverage of the toolbox controls.
As Graham mentioned above, the Head First series brings a lot of fresh air into this space, as do the titles from the Pragmatic Bookshelf (no matter how uncool the word ‘pragmatic’ sounds.) It’s a pity that both series don’t have more .Net coverage.

“that’s the equivalent of writing code in Notepad.”

While it may be painful, I find it necessary sometimes to use the most basic editor. Although if I can I use Notepad 2 to make things a bit easier on myself.

Amazing!

I have both of these books and came to the exact same conclusion. Petzold’s book was a real dud. I had a heck of a time getting through it. It was dry and boring with no clear delineators between topics. He would roll from one topic into a completely unrelated topic with little more than a blank line separating them. It makes going back and finding a specific piece of information virtually impossible.

Nathan’s book is much easier to read and is full of great information. I’ve actually read it twice!

When it came out, the Petzold fan club gave it good reviews because… he’s Petzold. But frankly I have never been so disappointed in a book before. I waited months for that book. But when it came it took months to get through. Absolutely terrible. Sorry Charles.

A word about color (in general… the above example isn’t too bad).

Maybe I’m old school, but the color highlights of code always seemed a bit amature-ish. Neat idea, but so often poorly done. Maybe if they didn’t strive to use so many colors, or maybe if they varied the brightness a bit (they always seem too bright).

However, I have to say I love bullets and sidebars (so long as the sidebar doesn’t make me span several pages).

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.