What makes a good technical book 'good'?

Question

I'm writing a technical book (plug - all money goes to charity so it's not so evil). Though I'm half done, I'm still constantly trying to figure out what makes a technical book really good. I don't aspire to be in the realms of a K&R or Peter Norvig or Charles Petzold or Larry Wall.

But when I pick up Adam Nathan's WPF book or any of Jon Skeet's books or Sam Ruby's REST book, something makes them stand out. I have a few ideas on what they are (authoritativeness, passion, opinionated, author experience, easy language) but I would love to hear the SO's community's thoughts.

I would also like to hear what people would like to see in a Windows Azure book but frankly, that's the lower order bit.

Answer 1

Well, my personal pref is books that are reference style, where I can just pick it up flick to a topic I want to know about and read just that portion without having to have read scads of other stuff first....not always possible, but thats the idea for me.

The only tech book I have ever read from start to finish is "Code Complete" but I think that book is a very rare example of a tech book that can be read that way. (of course this is very subjective)

Answer 2

It looks great on my desk.

Answer 3

Book that provides examples of how the theory described therein relates to real life problems. In particular, books that start with a problem description and then iteratively improve upon a solution to that problem really appeal to me.

HTH, Good luck with your book!

Answer 4

I would say that humor plays a small part of it. Small doses of humor applied here and there--with the goal to avoid the reader from falling asleep--are especially a good idea if the book is a start-to-finish thing.

If it's a reference style book like Tim J suggested, then humor obviously is not as needed. For that type of book, the reader just wants to learn a specific topic quickly.

Bonus points if humor can be integrated with real life problems--as EightyEight described.

Answer 5

Cartoon Foxes.

In all seriousness though, having some of the author's charisma/personality shine through really can make technical texts a more pleasurable read.

Edit: Here's a link to the wikipedia page with mirrors of the original text which was removed following why's mysterious disappearance in 2009.

http://en.wikipedia.org/wiki/Why's_(poignant)_Guide_to_Ruby

Answer 6

One word: "thin".

I'm tired of buying 500-1000 page tomes that are impossible to get through and full of filler.

The very best UML book ever written is Martin Fowler's "UML Distilled". Its chief virtues are technical depth and dense packing. It's less than 1/2" thick and can be read through quickly.

I think the industry can use more of those.

UPDATE: And did I mention code examples that actually work? I like to see something meatier than "Hello Word" that compiles and runs as advertised. There's nothing worse than code samples that don't run.

Answer 7

I like a book to be a bit funny. The first edition of Code Complete, for example:

• The Coding Horror icon
• The Socratic dialog about whether to write comments

Meyer's books, too, for example the first sentence of the first chapter is:

Getting used to C++ takes a little while for everyone, but for grizzled C programmers, the process can be especially unnerving.

"Grizzled"! That's funny! It's an insider joke (i.e. playing on a stereotype), and a "Yes we share vocabulary" moment, and with an actual relevent subliminal message to it (i.e. that it's time to slow down and pay attention).

Answer 8

For me...

• Detailed Examples. Not long, just short and to the point.
• Entertaining to read (Humor is a plus)
• Contradictory to my previous point...serious when it should be. If I want a joke book I'd buy one. Too much is too much and a good author knows when that point is reached.
• Points are easily communicated to the reader and technical jargon is toned down. Not all of us know what an ArrayList is for example, that is why we are reading the book in the first place. After the reader is acquainted with the term, using it later in the book is fine. I expect the last few pages to use more technical terms than the first few.

Answer 9

I really like the head first books. They seem a little bit childish and maybe to many people a little bit superficial but for the persons this books are intended to the are great to read. This books have a philosophy how their content is delivered to the reader and fully follow them.

Some other points I like:

• Humor was mentioned before I think it is especially important to not be to serious about your self and the topic. You have to be able to make the reader smile.

• Working examples. Every time you have an example make the user able to write it down and then compile/execute it. There is nothing worse then having some pseudo code or a code snippet that you want to try but because serious things are left out for simplicity aren't working. The Pragmatic Programmer used a special technique for this. The wrote their book in latex and included all their example every time the book was build from code files and before they included the code this code files were executed so that they had a continuous integration test for their book. If you need to use snippets provide the rest of the code online or on a cd.

• Variation. Nothing more boring then the same style in writing and desgin with nothing to get your attention or show a problem from another side.

Answer 10

That's interesting. I'm worried that as an author, I make the book too thin, the reader feels he/she didn't get enough value for money. Since most times the effort involved in a thin book is the same (if not more), than a fat book, it can't be much cheaper than a 'fat' book either. Is there a sweet spot for a technical book? My gut feeling is that anything over 350 pages and it starts to feel heavy.

I tend to feel cheated if the book includes (or, worse, consists of) reference material: for example if it lists, on paper, all the methods and parameters and so on in an API. I'd rather read that kind of material online.

Answer 11

Examples that work. I hate going through the effort to follow the example, and discover things missing. After all, if I'm reading your book, I probably don't know all of those "everyone knows those things" pieces. Give complete examples that I can compile and run! If I need a certain include file, tell me, and tell me where to get it.

Oh, and make it well written. I don't know how to describe good writing, but I recognize it when I see it. Good writing is a skill that most tech writers lack.

Answer 12

Before anything you need to see Philip Greenspun's exsperiences writing a book The book behind the book behind... explains quite a bit about publishing.

Answer 13

Sometimes I think humor can detract too much from the subject matter if it's quite heavy going, or mean that the book doesn't really stand up as a reference tome - it's annoying to keep reading the same average gag over and over every time you need to look up a certain topic.

What's more important than humor to me is personality - where you can tell the book was written by a human, not a vulcan, and you begin to feel a bit of empathy or a connection with the author. This is what makes a book interesting and readable without going too near the "For Dummies" school of naff cartoons.

Answer 14

Make sure it has a good index.

It's not the most important thing in a book, but I've noticed strong positive correlation between the quality of the book and quality of the index.

Answer 15

Define your intended audience and write for them. Books that try to be everything to everyone fail horribly. Too basic and it will frustrate people with some expertise; too dense and it will frustrate people without the prerequisities. There can be no book on any given subject that is perfect for everyone, so don't try to make one.