On Writing Books for Programmers

http://the-reviews.appspot.com/article/on-writing-books-for-programmers

by nvictor • 15 years ago

38 15 15 years ago

the-reviews.appspot.com

bediger• 15 years ago

This article makes a ton of good points, but misses typesetting. A lot of the books he cites got typeset with troff. Certainly all of Kernighan's books, and all of Stevn's books, got typeset using troff.

It's not that troff is so great at user input (it's not, it's frighteningly difficult) but that the output is so good. I know that Stevens tweaked the troff to get good output, too. No orphans, widows or rivers for him.

Books typeset using "Word" are typically, though not always, not good books. Word's output is usually a little goofy. Word also seems to tempt people into doing stupid things, too. Maybe Word is too easy, and authors end up writing too much, but something causes Word-set books to be a bit worse in general than other typesetting-method-books.

beej71• 15 years ago

Word processors are just not typesetting/page layout tools, generally.

Plus, good page layout is hard. I certainly have plenty of bad examples on my shelf--not that I'm brilliant at it myself, or anything.

cema• 15 years ago

What about good old LaTeX?

me2i81• 15 years ago

troff is kind of long in the tooth these days as its niche has been mostly taken over by TeX/LaTeX. The only place I ever see nroff/troff used nowadays is Unix manpages. Old Bell Labs guys probably still use troff. Just keep in mind that you don't have to use Knuth's fonts to use TeX, just as you don't have to use Times Roman to use troff.

wmat• 15 years ago

Great article. I particularly like the advice to keep the length of the book short. However, what do you do when you can't, break it into separate Volumes like Knuth's, TAoCP?

ddbeck• 15 years ago

Volumes, sure, but those volumes need to specialize and, to a certain extent, stand alone. In other words, don't just put "to be continued" at the end of a chapter; find a logical place to segment your work.

fredoliveira2• 15 years ago

This is actually quite timely advice, as I'm co-authoring a book for O'Reilly right now. I do question one of the points made about book length, though - do people really prefer smaller books? This is purely based on my perspective (so should be taken with a grain of salt) but I assumed that people prefer larger volumes because it gives them the warm fuzzy feeling (tm) that they're going to find whatever they need inside. (We are going with a small-ish book, however.)

Any thoughts? Thanks guys!

davidmathers• 15 years ago

people prefer larger volumes because it gives them the warm fuzzy feeling (tm) that they're going to find whatever they need inside

That's how I felt when I was a novice. It didn't take to long to realize that most large books are padded with filler though. Not only did I find much of the content useless, I found the lack of concision made them harder to learn from.

do people really prefer smaller books

Absolutely. If I see a large book at the bookstore I don't even bother taking it off the shelf. Reference books are the exception, but I mostly use the web for reference.

fredoliveira2• 15 years ago

Thanks for your thoughts. I do prefer smaller books myself, but I keep seeing people buying large reference books which end up being wasted money in a time of Google search.

ScottWhigham• 15 years ago

This doesn't seem correct to me. This seems exactly opposite of "correct" and feels more like, "This is what I like so therefore it must be 'right'."

Walk into a bookstore or browse an online bookstore. Find the most popular/stocked books. What are they: big, small, in-between? This can't be hard to find out for yourself.

If you truly care about making something that "the people want", then do your research and find out what "the market" is buying; don't just depend on one guy's answer on HN to control how you write/steer your book.

And David - I mean no disrespect by this. I'm not trying to single you out; I feel the same way as you about books I want today. However I do disagree that "people" prefer small books.

kenjackson• 15 years ago

I also prefer shorter books.

Some other advice -- short sections. I hate hitting a 50 page section. I like to finish a given section/chapter in one sitting.

Also, practical examples are nice, but make sure they're easy to digest. If I have to whip out my old calculus book to understand the problem you're solving then you're losing points -- unless you're doing a very targeted book I don't want to read, "But first we need to understand the math for wavelets..."

johnzabroski• 15 years ago

I prefer books that are highly rated on Amazon.com. I generally don't care how long they are. I mainly ask myself,

Am I the right audience for this book?

If I am not the right audience, can I gain a new perspective by reading this book?

Who is recommending I read this book?

Am I buying this book just because I lack expertise in an area? If so, why am I not asking an expert what book to read and what to look for in a good book? See, for example, Victor A. Wagner Jr's guide to reading C++ books: http://www.rudbek.com/books.html On IRC chat, Victor usually repeats the advice in Peter Norvig's essay Teach Yourself Programming in 10 Years

If I am reading Lambda the Ultimate, and somebody with seniority on that site (e.g. Allan McInnes) says read Franklyn Turbak's book on programming languages, then I generally follow that advice. Smart people tend not to read nor recommend crap.

DannoHung• 15 years ago

Hell yes! I want the information delivered concisely and clearly.

I'm reading Odersky's Scala book right now and it just GOES AND GOES AND GOES. It makes Scala seem like the biggest gorram language on the planet. The worst part is that things get harder to understand because one part of a chapter hinges on understanding of something from 300 pages ago.

I'll take time to highlight what I find to be one of the most important sections of the book: Type Parameterization

It starts by explaining the concept of a functional queue. This has nothing to do with type parametrization except that it will later be an example of how to use type parameterization and it is a type that can be parameterized. It then goes on to explain make constructors private and private classes.

Finally, it introduces variance annotations. Ah hah, the first part of the chapter pertinent to its heading and we're only 7 pages in! Herein, the concepts of covariance and contravariance are briefly explained, though, for me, not with enough detail to actually understand them. We then compare how Scala handles variance next to Java, a language that I am not learning, though it is somewhat pertinent in that in order to maintain binary compatibility with Java some stupid crap you should't do except if you're using a Java library is possible. Next there is an explanation of how the compiler checks variance annotations which is useful, but something much better left to an appendix given that it will only be needed to understood if you get compiler errors.

We get to the next actually useful part of the chapter in learning about lower bounds on type parameters. Now we go back to contravariance. And then upper bounds on type parameters, though not before detouring into privacy scoping rules for objects, another rather irrelevant subject.

Now at this point, I have gotten it set in my head that covariance, contravariance, and upper type boundaries and lower type boundaries are all very closely related. And it takes me about 4 hours to figure out that they're not except in the sense that you can use said annotations in a parameterized type.

In total, the chapter is nearly 30 pages long and relates about 5 useful pages of information about type parameterization in Scala, the high level concepts of which could have been explained far more clearly in half a page each and by explaining how they are not strictly related. It's also really great that pertinent information about private classes and private constructors is in an unrelated chapter.

What is unfortunate is that this is the bible for this language. New programmers are recommended it. Personally, I'd be swearing Scala off if it wasn't so clear to me that it was a really powerful language worth knowing. But the arrangement of this book is like a utensil drawer crammed full of forks and knives in a completely haphazard fashion.

mark_l_watson• 15 years ago

I think so: shorter is often better. I have read 6 technical books in the last 6 weeks (4 were free from the publishers, which was really nice). One of these books would have been excellent if it was shorter: the author would make a good point and then repeat the same thing one or twice in the next dozen or so pages. I think that author was not well supported by his technical editor and editors. A good 400 page book could have been edited down to an excellent 200+ page book.

deadmansshoes• 15 years ago

While short snippets of code to illustrate a point are useful, I find the reams of pages devoted to entire sample programs pointless. When does anyone have the time or incliniation to go the an associated website download and compile code, whilst reading a book?

I also see little point in reading a book on a subject until you've at least played with the technology yourself.

On Writing Books for Programmers

Related Stories