What's in a Nutshell?
by Bruce A. Epstein11/20/2001
The guidelines to follow should assist authors who are writing for the In a Nutshell series. For good examples, see Webmaster in a Nutshell, 2nd Edition and the seminal Unix in a Nutshell: System V Edition, 3rd Edition. The well-known Java in a Nutshell, 3rd Edition is not particularly Nutshell-like, but it is a good example of the flexibility within the series. Nutshells should be 300 pages to 400 pages in length, but some run less and many run longer. If you exceed 400 pages, do so with good reason, not simply because of flabby editing.
Nutshells are intended to remind, refresh, summarize, and answer specific questions. The subtitle for Nutshells is usually A Desktop Quick Reference, and Nutshells should be daily companions. Authors should find their own Nutshell book a convenient reference. If not, it needs more depth.
A Nutshell is not a tutorial (as is the Learning series, for example) nor should Nutshells provide infinite details, as do the Mastering series. If something is a learn-once-and-put-it-on-the-shelf explanation, it might not belong in a Nutshell book. Nutshells should not include an exhaustive language reference, as do Definitive Guides, but Nutshells can and should include reference sections with, say, ten to twenty commands per page.
Authors need not assume prior knowledge of the subject by the readers, but they should assume some prior knowledge of the context in which the program is used. For example, Webmaster in a Nutshell summarizes HTML tags but assumes readers know what HTML tags are and how to use them. However, authors must provide a complete description of the product being documented. For example, when documenting a programming language, you can assume that readers know what a debugger is, but you should not assume that they know the specifics of the debugger used in the examples. Tell them how to step into a routine, watch a variable, and set a breakpoint in the tool at hand. If you need to explain something, do so quickly, and assume the reader is both smart and impatient.
Stick to your topic. In Dreamweaver in a Nutshell we don't try to teach HTML, XML, Web design, and so on. We teach Dreamweaver and its use. That said, we offer ample advice on peripheral topics, if not primers on those topics. We assume users know what XML is, but we tell them how to import and export XML from Dreamweaver. Almost all tools are used in context with other tools. Explain the peripheral technologies enough for users to get their job done (no more, no less).
A Nutshell is not for handholding. Assume that readers have specific projects in mind and they want to complete them quickly. For example, don't tell readers that they should add video to their Web site for impact. Assume that they have decided to include video, then tell them how to do it, including the pitfalls if it is ill-advised. Tell readers when not to use a tool and offer a better alternative, such as: "Don't use XYZ for PDQ task because it is overkill. You are much better off using ABC because it has a larger installed base, a smaller footprint, and broader compatibility."
Include everything that is important. Leave out what is not important. Nutshells should address 90 percent to 95 percent of the readers' questions, not a mere 80 percent (for example, ignore the 80/20 rule). Nutshell authors must keep their egos in check and avoid documenting 100 percent of what they know. No stories about the author's favorite client. No retelling of the history of Unix. The readers don't care. Typical authors must also do further research into topics where their knowledge is slim.
The index must be superb if the book is to be an effective reference. The editor and author should suggest terms to the indexer and carefully check the proposed index.
Prose is acceptable, but Nutshells should juxtapose facts and present conclusions, not meander through sample projects that leave readers needing to draw their own conclusions. If it can't be summarized in a table, a numbered list, or a bulleted list, it might not belong in a Nutshell. Even if you use prose, summarize the material in a table before or after the general text.
Include twice the information in half the space (or better). Read other books on the market. Highlight everything that a reader needs to know. Strike out everything else. Everything you've highlighted belongs in a Nutshell, everything you've stricken doesn't. Cover in 150 pages what other books cover in 500 pages. Then add another 250 pages of stuff that the other books omit but readers need to know. Avoid excessive use of notes and warnings. Everything in the book should be worthy of highlighting, so reserve notes and warnings for really important stuff. If you put it in a sidebar, it might not belong in a Nutshell.
Nutshells are not necessarily dry, nor are they without opinion. To the contrary, the author should make forceful recommendations about what to use and what to avoid. Nutshells should not simply summarize the tool, but rather tell the reader what the author knows that will help cut through the chaff.
Respect the readers. Assume that they have very little time and want to solve their problems immediately. Don't spend time waxing poetic about why a tool is so cool. Focus on the reader's needs, not the tool alone. If you can explain a peripheral topic in a few sentences, don't send the reader scurrying elsewhere for details. If a topic is important but beyond the scope of the book, refer the reader to a Web site instead of bogging down the Nutshell book with details. For example, a Nutshell programming book should not explain the binary number system unless it can be done in two sentences. Assume the reader knows it already or doesn't care. Refer them to a Web site if you feel compelled.
The content in a Nutshell must be comprehensible by a savvy novice yet be of lasting value to expert users. Include every relevant thing that is hard to discover and hard to remember. Work hard on the organization of the book and make sure all tables are complete (keyboard shortcuts, menu commands, and so forth).
"Nutshell" is not synonymous with "superficial." A Nutshell should surprise the reader with its depth and breadth. The key concept is maximum information density.
Bruce Epstein is the author of O'Reilly's Director in a Nutshell and Lingo in a Nutshell, coauthor of Dreamweaver in a Nutshell, and he is the editor of ActionScript: The Definitive Guide. He has been a multimedia programmer and consultant for ten years, specializing in Macromedia technologies including Director, Dreamweaver, and Flash. He is a frequent online contributor to Web sites such as the O'Reilly Network and the IBM DeveloperWorks Startup Zone.
