Textbooks

One of my projects for the summer is working on a philosophy of science textbook I've been developing bit by bit for a few years now.

It is one of the world's worst kept secrets that textbooks, required for virtually every course, tend not to be all that helpful to students. I can't count the number of times I've heard students tell me, "I tried to read the book, but I just don't get it" or "I only understand it when it is explained in class." I don't know how much of this is a result of (1) students lying and having not really read the textbook, hoping to be spoon fed the information instead of doing the hard work themselves (2) instead of active reading, students merely skimming the textbook and not really sitting down and reading carefully, working through problems, outlining arguments,..., or (3) textbooks not being a successful pedagogical vehicle.

My concern is the last one. Everyone who writes a textbook goes into the project thinking that this one will be different. This is going to be the textbook that succeeds in being clear, engaging, and instructive. And, of course, most fail to meet that expectation.

So what is it about textbooks that you really hate and what examples can you think of that made a textbook successful? What should I avoid and what should I try to include?