The In a Nutshell Vision

by Tim O'Reilly
September 1997

There is an increasingly large population of users, programmers, and administrators with five, ten or even fifteen years of experience under their belts. They don't need a lot of handholding. They just want the facts.

O'Reilly's books have always been no-nonsense. But the In a Nutshell books raise that philosophy to an art form. What is it that a user is going to need to look up again and again? What is the critical background information that will allow a new but fundamentally sophisticated user to make use of that reference information? We see the In a Nutshell series as a broad-based consumer series for this new--and growing--class of sophisticated users.

We believe the time is right for a new value proposition in computer book publishing: high-end books at low-end prices, for sophisticated users who need the facts but not the frills.

The Facts

In the computer book market there seems to be a strong desire for the high level treatment of many topics that have in the past been written primarily in a tutorial fashion. In a Nutshell books by definition take the air out of huge books or even a series of books, and boil them down into one compact reference book. Key concepts can be found condensed into a page or two, so sophisticated users can quickly review a concept and say, "I've got it!" The user may not have the experience to think of an idea themselves, but once they have the idea and a few critical facts, it makes perfect sense to them. In a broader sense, In a Nutshell books transfer crucial knowledge from power users to the intermediate or novice user who has the ambition and sophistication to become a power user.

The Devil is in the Details

The authors of these books are very diverse. However they do have something in common: they take a topic and drill down, expand, and delight the reader by providing useful information that the reader didn't even expect to find. It's obvious to the reader after discovering this information, but not before. This "leap of usefulness" is crucial to an In a Nutshell book, for by thinking ahead of the reader and providing this type of value, you will be delighting the reader.

The Essentials

Most authors in this series are either experts in their topic, or they tend to be very agressive journeymen who learn by doing. Regardless of their expertise, it can be difficult for prospective authors to attain a complete understanding of the In a Nutshell concept. As a possible starting point, the following list of tips and suggestions is designed to help authors who want to add to this exciting series:

• Most people who talk about wanting to do a book in this series don't seem to break the idea that it is somehow supposed to be tutorial or explanatory in nature. One suggestion would be to add any necessary tutorial material AFTER the core reference material has been defined.
• Something authors must always keep in mind is that these books are designed for "look up" rather than for reading. The reading part (introductions, tutorials, etc.) exist only to provide context for the "look up" portion of the book.
• Begin the process by creating a long list of "need to know" items (i.e., 100 important things that you'd want to tell someone about a program, for instance), regardless of taxonomy, and THEN come up with the best way to represent them. The point isn't to come up with a taxonomy for the system, but to come up with things that people wish they knew, and then create a system for how to find the references to them.
• It might make sense to approach an In a Nutshell book in layers, rather than from beginning to end. That is, write the introduction to every section, giving the rationale for why that information is there and what someone will get out of it. Then arrange those sections into a reasonable order and argue over the justification, and only then fill in the details.
• Another approach that may be helpful is to think about what you would use the Help for in a given product. Now, can you think of a quicker way to get the same information to the user by the way you organize the presentation or access to it in print?
• It seems like the more "impossible" a topic may seem, the more likely you are to get past the conventional models of what you can fit into a book. If you don't think you have to explain it all, but only need to list information in an effective way for someone who already understands it, a lot more becomes possible.
• Many topics that seem too thin can in fact become an In a Nutshell book if one thinks about the ripples that spread out from a rock tossed into a pond. In a similar fashion, a topic can broaden itself out into concentric rings of associated information that is needed by the user and is thus very valuable.

In a Nutshell Examples

UNIX in a Nutshell was the first in the series, and shows how the In a Nutshell approach can be applied to a system with a lot of detailed commands and options to remember. This is the most obvious case: everyone knows that UNIX has hundreds of commands, each with dozens of obscure options.

But look how the book grows from that point. Many of the larger programs--vi, ex, sed, awk, troff, the shell--have command sets of their own. There are common features (such as regular expressions) that are used by a number of programs, and so deserve a separate section. There are even things--like an ASCII chart--that are not properly part of UNIX, but are still useful for someone grappling with certain utilities.

Tutorial material is used sparsely in this book, but it is there. For example, look at the section on awk. The bulk of the material is a command reference, but there is enough of an intro to remind the occasional user about the basic structure of an awk program. This, and the command reference, is enough for a sophisticated user to get started.

WebMaster in a Nutshell takes a very similar approach, combining quick reference chapters on each of a number of topics important to the webmaster: HTML, CGI, Perl, web server configuration, and so on. It gains density by collecting reference information on topics that are used together, but not always documented together.

Java in a Nutshell has a much larger tutorial component--several hundred pages, in fact. But the tutorial is extremely fast-paced, and aimed at experienced programmers. When this is coupled with the detailed reference material on each of the Java classes that makes up the rest of this book, you have all that a sophisticated user needs.

Java in a Nutshell also demonstrates how indices can add a lot of value. Fully sixty pages are given over to two indices, a standard page index, and a cross reference index showing the relationships between classes, methods and fields.

NT in a Nutshell tackles the problem of finding options in an enormous GUI. It uses "GUI maps" to make it easy to find options that are buried deep in a tree of menus and dialogs. It also documents the oft-neglected command-line interface to NT, and gives tutorial information on a few especially important topics.

By contrast, Photoshop in a Nutshell follows the structure of the menus and screens. This is not normally an approach we'd recommend, but the authors pull it off because of the sheer depth of useful information they provide about every item. For example, the book uses "File Save" to launch into a serious reference on the various file formats into which you can save, applications that use them, and what the tradeoffs are in terms of image size, loss of data, and so on.

Taking a look at these various examples, you see that there isn't a single format for an In a Nutshell book. But each of these books has created a density of information about its topic that makes it a unique value.