« Katrina | Main | Conversational writing kicks formal writing's ass »

Reference vs. Learning: pick ONE


The biggest problem with many tech books (and tech training) is indecision. When the author can't decide between creating a reference or learning book, they often try to do both. That rarely works. So the second most important question to answer when you start to write a tech book (or a book proposal), instructional manual, or training course is what's my goal?

And the most important question is, "what's the reader's goal?"

When a non-fiction book (especially a tech book) doesn't sell, or a training course isn't successful, it's often because the reader was on one end of the graph while the writer/course developer was on the other. Or because the author/teacher believed that giving information was the way to communicate knowledge and understanding.

The difference between facts and information is straightforward: information organizes facts into a meaningful pattern. Without information, data and facts can be arbitrary and useless. There's a crucial place for reference information, and information architecture is art + science. (Two info architect bloggers are Louis Rosenfield and Jesse James Garrett, both who've written books.) Turning facts and data into meaningful information is--for a lot of books, websites, and manuals--often the destination. The thing the users want.

The big problems happen when the user wants and needs knowledge and understanding but gets only information. If information is a meaningful, useful organization of fact and data, understanding is about knowing how--and more importantly why--to apply that information to do something creative.

Look at the tech books on your shelf. Chances are, more than a few of them exemplify what Prentice-Hall editor Greg Doench refers to as one of the seven deadly sins of computer book authors: greed. He calls it greed because he reckons it's the author's way of trying to capture the largest possible market for the book. He spots this most often in book proposals by first-time authors, he claims, when they make statements like "this book is for everyone from beginners to advanced users" and "after they learn from it, they'll use it again and again as a reference."

I don't think it's actually greed, of course. Often the authors don't have enough user data on what readers do want, so they're trying to be safe and do both. Or they're trying to make a book that simply is more helpful because it does offer both information and understanding. It's so tempting to try to offer something to readers where they need buy only one book that both teaches and is a reference-- it sounds so user-friendly. But it's nearly impossible to do well.

Our advice to our authors is: "You MUST choose one, and you must commit body and soul and keyboard to doing that one single thing--either reference (data and information) or learning (knowledge and understanding), while letting go of the other. Accept that you can't meet both goals, and that most of your readers don't have both goals, and figure out the best way to satisfy that one goal."

How do you decide which to choose from? Only your users can tell you. There is an interesting trend that might help, though--early adopters tend to need the least amount of hand-holding, and not only can but want to jump in armed only with a reference and a few tips. You just point them in the right direction, give them the information, and they're running. It's these early adopters that will help define the kinds of user stories that those of who write about more mature technologies will use to teach for knowledge and understanding.

Tim O'Reilly has been giving a talk on What Book Sales Tell Us About the State of the Tech Industry, and O'Reilly's extensive data crunching (for all publishers, not just O'Reilly Media) has consistently found that when a technology is fairly new, the bestselling books on the topic tend to be more advanced, less step-by-step learning. But as the technology evolves, the balance shifts and the bestsellers are the beginning books while the advanced books start to drop off. This isn't completely intuitive unless you think about who the early adopters are. So for example, the bestselling Java book today is a beginner book, and the best selling C++ books are also focused more on beginners, where a few years ago, the bestselling Java books were advanced reference books, not "learning experiences."

This table shows a few of the key differences between Reference and Learning, and explains why we (my co-authors and I) believe so strongly in picking only one side of the table.


Actively trying to do both means you'll probably do both mediocre at best, and today there's not enough tech book business (down to 1/10th of what it was in the bubble) to support anything but the books that know and meet their goal. Obviously there are places on the venn diagram that overlap; I can't conceive of a learning book that does not offer facts and information, and a great reference book does provide learning by using an information architecture that makes the knowledge and understanding explicit. Some of the best reference books organize the data in a way that offers not just meaning but a revelation... a higher pattern I wouldn't otherwise have seen without that organization. And those higher level patterns and revelations are memorable, just as a well-crafted learning experience.

The other big thing I'm not addressing here is that there are a lot of subgenres in each of those categories. It's not just a matter of a straight dictionary-style reference book vs. a fist-time-beginner learning book. You have tutorials, cookbooks, hacks, hands-on expert walk-throughs, nutshell books, and "missing manuals". Many of these have at least some element of each side of the learning vs. refererence table. But the point isn't about avoiding the other side of the table--it's about having only one thing as your ultimate goal, and then putting in only what supports that goal. It's about choosing NOT to include things if those things are there simply to try to satisfy both sides of the table (i.e. to be "greedy").

Footnote: when I mention the "greed" thing, it's from a great talk Greg gave at JavaOne on how to make a bestselling computer book. His slides aren't online anywhere, but he's given me permission to reproduce some of it on this blog, so I'll be putting that up soon. It's especially helpful to those who want to propose a book to a tech publisher (today's tip: do NOT put "this book is for both beginning and advanced users" in your proposal) ; )

Posted by Kathy on September 4, 2005 | Permalink


TrackBack URL for this entry:

Listed below are links to weblogs that reference Reference vs. Learning: pick ONE:

» Blog Writing from Chasing the Wind
I found this entry on Creating Passionate Users...it's worth a brief read! The question Kathy Sierra poses is: why do you write? Is it for facts? Or is it for information? In order to be good writer, you must know... [Read More]

Tracked on Sep 5, 2005 8:49:21 PM

» Creating Passionate Users: Reference vs. Learning: pick ONE from My Own Little World
I like the head first series of books, I am enjoying their book on patterns right now. Here is a great blog post on writing books and being clear about which type you want to write. If you have to write tech doc (and who doesnt) ... [Read More]

Tracked on Sep 6, 2005 10:01:36 AM

» Why you should start blogging right now! from Nev's blog
What? Another blog? Arent there a million already? Why are you starting a new one? Answer : Because real information is useful. The computer book publisher OReilly found a funny thing. Common sense would tell you that when a... [Read More]

Tracked on Jun 20, 2006 7:45:52 AM


I got about half way down your comparison table before I thought that the left side seems generally descriptive of tags (e.g. del.icio.us, flickr.com), and the right of weblogs (e.g....well...this), both of which seem to be popular among the same group of people. Maybe that's because they accomplish such different goals. I wonder if reference and learning couldn't be combined well in the same book, just so long as they were kept distinct. For example, I often use php.net for reference, but then below the reference is comments, from which I've learned a lot.

Posted by: Scott Reynen | Sep 5, 2005 8:37:07 PM

Scott, I think you're absolutely right that both reference and learning *can* be combined well in the same book if they're kept distinct. The biggest hurdle with that becomes the *size* of the book... there's a physical threshold at which a book is too darn big to flip through as needed at your desk, or too big to, say, take on the train with you for studying. But if the topic is narrow enough, you could defintely do it. You hit the key -- it's about seeing each of those things as *separate* top-level goals, and serving each one well. When we finally one day DO have electronic books that are as usable (readable) as paper, we'll have the most elegant solution--you can have learning and reference material that's all linked together, so if you're learning and want more reference, you can click, and vice-versa.

Obviously lots of websites and CBT already do that, but the problem today is that reading text on a screen is still roughly twice as difficult (physically) as reading text on paper, so it works only for smaller, bounded topics as opposed to learning a big topic from the ground up. But we'll get there...

But it also requires that you have two authors, or one author who can wear BOTH hats well. For example, although I have some information architecture in my background, I'm not that good or experienced at it-- so while I'm capable of designing a learning experience, I'd need someone more qualified to help build great reference materials. But that collaboration would probably improve *both* pieces... hmmmm... you just gave me an idea : )

Posted by: Kathy Sierra | Sep 5, 2005 8:55:06 PM

That's why I like the Ruby Pickaxe (http://pragmaticprogrammer.com/titles/ruby/) so much. It is divided into four parts. The first is the the beginner's section. The second is a look at the advanced options you have in Ruby. The third part is about advanced stuff like extending Ruby with C and other things. The fourth part is a complete reference of the Built-In Classes and Modules + the Standard Lib. The first three parts take up one half of the book. The reference takes up the other half. Perfectly balanced.

In the regard of your post this book is clearly a role model for a combined effort. It is a truly amazing mixed reference / learning combo. The best book about a computer language I have ever read. First I learned Ruby by linearly reading the first half of the book. Nowadays I have it right beside me when I program in Ruby, regularly using the reference.

So, it is possible for an author to write such a book. But you have to clearly seperate the parts and effectively write two books.

Posted by: Sascha Ebach | Sep 6, 2005 7:29:04 AM

Thanks Sascha--I had planned to mention the Pragmatic Ruby "pickaxe" book as a book that IS great example of both learning and reference, but I forgot... so I'm glad you commented. I put that book squarely in the "early adopter" category, though -- most of the people learning Ruby today tend to be the more advanced programmers for whom the pickaxe book/format is exactly what they want -- "give me some great direction and the tools I need to jump in." It's a big book, too -- if they'd tried to include learning and reference for Ruby in a smaller book, something would have suffered. I also think the successful implementation of this book is more a testimony to how skilled and talented the Pragmatic folks are than a reason to think that it's a reasonable approach for "the rest of us" to try. I wouldn't have been able to pull it off, but it is the right book for the state of Ruby today, and they had the awareness to recognize--and deliver--what was needed and wanted.
The Pragmatic folks are among the very best tech book authors/publishers out there today, especially for the advanced developers (although they could do anything, they currently specialize in the advanced realm--but I've heard they'll be pushing those boundaries very soon). The founders, Dave and Andy, besides sharing our passion for brain-friendliness, are doing some truly innovative things with their business that are designed to help the user (and author). If any of you are thinking of proposing a technical book, I'd put them at the top of your short list for who to consider as a publisher.
Thanks again Sascha. We can all take a big lesson from these guys.

Posted by: Kathy Sierra | Sep 6, 2005 10:20:55 AM

There is one other set of books where this problem is even worse that computer tech books and it's books for Music software. Books that attempt to explain every aspect of Cubase, Logic, or Reason have never been able to teach me to compose anything at all with these extremely complicated programs. For some reason the music software book authors haven't quite got the grasp of what it takes for someone to learn how to use music software and produce a reference for the software almost every time.

It drives me crazy because I really want to know how to use the software to accomplish things.

Switching topics to books that do nail it, I think the Agile Web Development with Rails by the aforementioned Prag Programmers is an even better example of meeting both needs in one book. The first half is a tutorial leading to knowledge and understanding, while the second half which is clearly different from the first, is a great reference for Rails.

Love that book,

Tim Case

Posted by: Tim Case | Sep 6, 2005 10:55:04 AM

"...seven deadly sins of computer book authors: greed."

Well, I don't know about your experiences but mine has certainly been that that particular deadly sin comes more from the publisher side than the author side. I.e., look at how much of the authoring process is impacted by the horrible book development process. There's way too much BS before the project is started that is based upon "proposals" that usually bear little resemblance to the end result, there's way too little input/feedback during the early days, there's way too much feedback late in the project when it's often really expensive to change (time consuming, frustrating, etc.), there's often ridiculous time pressure (as well as the ridiculous lateness of authors getting manuscripts finished (because of e.g., the way overoptimistic "estimates" both from self-directed ignorance/etc. as well as due to the trying to make the publisher happey)), etc. Ugh.

On the author side, I think it's much more a question of trying to be everything to everybody (i.e., almost everybody wants to write e.g., "the great american novel") rather than monetary greed.

Posted by: John D. Mitchell | Sep 6, 2005 11:00:29 AM

John -- when Greg was talking about "greed", he didn't mean "monetary"; I think he meant it exactly as you put it, "trying to be everything to everybody" as in "greedy about wanting to satisfy (and capture) the largest possible audience". (and "greed" was the best fit for that in his entertaining-but-useful seven deadly sins theme ; )

All the things you describe I've heard before, but never experienced anything even remotely like that. I've had nothing but the best working relationship with O'Reilly (my editor is Mike Loukides) as well as my experience with Osborne/McGraw-Hill (my editor there is Tim Green). Nothing you mentioned (except for the missed deadlines ; ) has ever come up in any of the books I've written or helped with (six in the last three years).

And every author of a Pragmatic book I've talked to has had nothing but enthusiastic praise for their experience publishing with Dave and Andy. I've heard great things about Peachpit as well, from Dori Smith who's done several books with them.

But a lot of people I know and trust have described nightmare scenarios just as you mentioned, so I know it happens, but it's definintely not a given. I think it depends largely on the relationship between (and experience of) the author and editor. I suggest to anyone that if you don't have a good feeling about how things are going with your editor at the proposal stage, don't do the project! This should (and can) be a positive, energizing, make-the-reader's-life-a-little-better experience, not a nightmare of frustration. If any of those things had happened to me, I wouldn't be writing books.

The proposal can have a LOT to do with this; I'll say more about that in a later blog. Thanks John.

Posted by: Kathy Sierra | Sep 6, 2005 11:54:23 AM

I agree with John about the publishers being part of the problem. However, my experience is that publishers / editors are most pushy about format - I have usually won battes over content just because I knew the subject matter well and the editors didn't. But they have final say on editing, marketing and printing, and can't seem to help themselves screwing up a writer's message in a lot of cases....Having had three technical books published by third-party professionals, the only way I could probably ever consider the ordeal of writing another tech book is via self-publishing.

As for reference vs. learning books, In this age of the Web, I can't imagine using (or writing) a book for reference. Sequential lessons that require extended concentration are a good book format. However, an electronic format with a good search capability is so much better for reference. If I was to produce a reference book, I'd probably not even bother with a print edition, just electronic.

Posted by: Brian Benz | Sep 6, 2005 5:34:11 PM

I think this may apply to presenting too: make sure you understand whether you are training or persuading but not both:


Posted by: Ian Cooper | Sep 9, 2005 3:34:47 AM

You have made many good points.
John Denny of the Denny Group taught me the 3Bs of

1.Be there
2.Be brief
3.and be gone
brother daniel

Posted by: Daniel Eggink | Sep 9, 2005 11:14:10 AM

The comments to this entry are closed.