On Writing Books for Programmers

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.

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.

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..."

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.

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.