 |
For the cover of the first edition of
Effective C++, I envisioned Alexander
the Great cutting the Gordian Knot.
|
I'm getting ready to start work on
Effective C++11 (about which I'll have more to say in a later blog post), and this week I've been reviewing a manuscript for a new book in my
Effective Software Development Series, so recently I've been thinking a lot about what makes an effective
Effective book.
Effective books consist of a collection of technical essays ("Items"), where each essay's title comprises advice you should follow, and each essay's body consists of a rationale for the advice. In the third edition of
Effective C++, for example, Item 37 is "Never redefine a function's inherited default parameter value."
This format has always seemed pretty straightforward to me, but having reviewed dozens of proposals and manuscripts for my series, it's clear that it's not straightforward to everybody. A few years ago, I wrote up the following guidelines for authors of prospective
Effective books. Partly to remind myself of my own advice as I embark on a new book, and partly to have a place to point people who express interest in writing a book for my series, I thought I'd publish my guidance here.
Item 1: Keep Items short.
One of the things readers like best about
Effective C++ is the brevity of the Items. They're generally only 4-5 pages long, and that means that one can be read while waiting for a meeting to begin, during a quick break, even while using the bathroom. I discovered this when I came out with my second book (
More Effective C++), in which some items run for 10-20 pages. Big mistake! People want bite-sized chunks of useful information from an
Effective book. Give it to them.
Frankly, the constraint that Items be short is good for you as an author, because it forces you to think hard about what really needs to be included and what can be omitted (see below). Also, it allows you to produce a book of typically under 300 pages, and a book of that length is something you've got half a chance of keeping in your head all at once.
Regarding overall book length, there are two ways to approach the matter. It's a lot like packing for a trip. You can either:
- Choose all the stuff that you think you need, then find a big enough suitcase to hold it all, or
- Choose the suitcase first, prioritize everything, then put in as many high-priority items as will fit.
Effective books generally follow the latter strategy.
Think about your goals for your book. Is it to tell your readers
everything they need to know, or is it to tell them
the most important things? Remember that the longer your book, the less likely your readers will read all of it. So what would you rather have? A 250 page book that almost all readers read almost all of or a 500 page book that most readers read about half of?
It's your book, of course, and it's most important that you be happy with it, but you might bear in mind that I've published 140 Items on C++ programming spread across about 800 pages, but I did it in 3 different books. I think my readers like it better that way, because there's less for them to digest at one time. I know I like it better the way I did it, because I find it a lot easier to keep no more than 300 pages of material straight than to try to wrestle with 800 pages at once. Also, I like knowing that my readers are likely to read each book all the way through. I hate it when I work hard at writing something, only to find that some people stopped reading before they got to the end. I have a story I want to tell them, and it's important to me that they get the entire story.
If you have a lot to say, there's no law that says you have to say it in a single book. Splitting it across multiple books may end up serving everybody better.
Bear in mind that
Effective books are designed to be "the standard second book" on their topic. You should assume that readers know the basics and have another comprehensive reference available to them.
Item 2: Put Item titles in the imperative.
People read
Effective books for advice, to learn "the things the experts almost always do--or almost always avoid doing." They want to be told what to do or what not to do, so each item should give them an order:
Do this or
don't do that (ideally the former--see below). Statements are not as helpful as imperatives, so don't use statements as Item titles.
As an example, I could have worded this Item as "Imperative Item titles are good," but that's not advice, it's just a statement. "Put Item titles in the imperative" is advice. Your readers want advice. Provide it.
Alas, they sometimes want advice when what they really need is information. Fortunately, there's a way to give them both: use imperatives that begin with "Understand" or "Familiarize yourself with" or "Be aware of" or things of that ilk. For example, if you think that people generally fail to grasp the subtleties of some topic XYZ and you feel that they really need to understand it in order to be effective software developers, consider a title like, "Familiarize yourself with the subtlties of XYZ." It's still an imperative.
After reading your book, people will want a convenient summary of the advice it contains. If each Item title is an imperative, the book's TOC (Table of Contents) will be a summary of its advice, and that should be one of your goals: to have the TOC summarize the advice in the book.
Item 3: Make Item advice as specific as possible.
The best advice is so specific, it can be checked by a machine. In fact, many of the guidelines I put in
Effective C++ have been incorporated into static analysis tools. Specific advice is also good for code reviews, because it eliminates the interpretation factor; readers don't argue over what a particular Item means. They might argue over whether a particular Item is justified (see below), but if the advice is specific, they won't argue over what it means.
If you are having trouble making a guideline specific, it could be because the topic you are writing about in that Item is too general. If that's the case, perhaps you need to break it down into two or more separate (and more specific) guidelines. For example, if you're trying to offer advice about the proper use of inheritance, but you find that it's hard to be specific, because interface and implementation inheritance are so different, consider writing two items, one about interface inheritance, the other about implementation inheritance.
Item 4: Word Item titles carefully.
Your TOC summarizes your book's advice. Furthermore, your TOC consists primarily of your Item titles. That means that the most important sentences in your book are the ones making up your Item titles. All words in a book are worth agonizing over, but some are more agonizable than others, and the ones in your Item titles are the most agonizable of all. They make up the advice you want your readers to remember, even if they forget everything else in the book. As a result, you want your Item titles to (1) be easy to remember and (2) accurately summarize your advice on the topic addressed by the Item.
Resist the urge to choose titles that are catchy, but not informative. One manuscript I read had an item on using profilers to guide optimization efforts, and the Item title was "Optimize optimally." This is catchy, but it doesn't summarize the advice in the Item. Item titles are different from article titles. Authors often choose enigmatic article titles to intrigue people into reading the article. That's not the goal in an
Effective Item. Readers already have the book. You can expect them to read it. The goal of an Item title is to summarize in a few words the advice that will take several pages to justify. Remember: the Item title is "what." The Item body is "why."
When I write my books, I typically revise the wording of Items several times. I'll start with what I think I want to say, but after I've written an Item's body, I'll realize that my justification doesn't really back the title, so I'll revise the title. Or after I've written other Items, I'll discover that some of what what I wanted to say in Item n is now in Item m, so I'll go back and revise Item n's title to reflect the fact that it no longer addresses the concerns of Item m.
Any time my Item title is too long to fit on a single line, I'll try to come up with a shorter way to say it. Short Item titles are easier to remember than longer ones, and my goal is for my readers to remember all the titles of all the Items. The easier I make it for them to do that, the better my odds of achieving my goal.
You'll note that several of the other Items in this document relate to Item wordings. That's no accident. It's a reflection of the importance of Item titles to
Effective books. You've got just a few words to summarize the lessons of several pages of often complex material. Choose them carefully. They're the most important words in your book.
Item 5: Prefer guidelines that say what to do over what not to do.
Guidelines that tell people what they should do are more useful than guidelines that tell them what they should not do. If a programmer wants to accomplish task X, knowing that they should not do A, B, or C may narrow the design space, but it doesn't really tell them how to accomplish X. Any time you are tempted to start an item with "Avoid" or "Never", imagine the following conversation with your readers:
You: Avoid doing A.
Readers: But if I don't do A, how can I accomplish X?
You: Do B instead.
If you can come up with such a conversation, you probably want to word your Item as something like "Prefer B to A for X." (See below for more information on words like "avoid" and "prefer" in Item titles.)
Item 6: Tell the truth and nothing but the truth, but not necessarily the whole truth.
Effective books are short by design, typically only about 5 pages per Item. With such limited space, it's important to include only information readers really need to know. Your goal should be to help your readers, not to demonstrate your mastery of history or trivia, etc. After all, one of the things they are paying you for is deciding what they
don't need to know.
At the same time, you lose your credibility if you lie to your readers, so you must never lie. To avoid lying while also shielding them from information they don't need to know, you will need to fall back on weasel words:
typically,
generally,
usually, etc. You don't want to use these more than you have to, because readers will notice them, but if your choices are a two-page digression on how some bizarre machine or compiler that almost nobody uses does something in a strange way or slipping "virtually" in front of "all implementations," then "virtually" and its kin are your friends.
Item 7: Back Items with solid technical arguments.
The most common weakness I see in prospective
Effective books is that the Item rationales fail to make convincing cases for the Items' advice. This is critical! Remember, you're telling somebody what to do. You're probably asking them to change the way they do things. If they're going to change their habits, and especially if they're going to let you push them around, they'll demand a good reason, and it's your job to give it to them. You should assume that your readership is smart, experienced, and critical.
Effective books aren't introductory, so your readers already know some of what you're talking about. Some of it they know as well as you do. If you tell people to do X, but fail to acknowledge that it's impractical some of the time, they'll notice, and you'll lose credibility. If you tell them that they have to do X because of Y, but Y isn't true, they'll notice, and again, you'll lose credibility. You can't afford to lose credibility, because if you're not credible, why should
your readers take your advice?
In addition, there are almost certainly going to be exceptions to any advice you can offer, and one of the most important things you must do as an author is explain to your readers when your advice applies and when it does not. The Item rationale is the place where you do that, at least implicitly. For example, I spend a lot of time in my C++ books talking about how to prevent resource leaks, and much of my advice boils down to, "Do this, because it helps prevent resource leaks." At one point, I was talking to engineers who work on the software that runs inside missiles. Their programs run until the missile hits its target. They don't care about leaking resources at program shutdown, because their programs never shut down. They stop running only when the bomb goes boom. As a result, they feel free to ignore some of my advice, and that's perfectly reasonable. But the only way they know that that is perfectly reasonable is because my books make clear the technical motivation for the advice I give. When that motivation fails to apply, so does the advice.
Item 8: End each Item with a summary of its advice.
The old saw is "Tell 'em what you're going to tell 'em; tell 'em; tell 'em what you told 'em."
Effective Items are similar, but not quite the same: Tell them what they need to remember; justify it; remind them of what they need to remember.
If you've worded your Items correctly (see above) what they need to remember is the Item title, a single sentence of only a few words. The justification typically runs 4-5 pages, and that's where you deal with implementation strategies, portability issues, exceptions to the rules, explanations of why things are the way they are, etc. By the time you're done with that, there is every likelihood that your readers have forgotten the main point you initially set out to make. You therefore need to remind them. It doesn't need to be long-winded; a sentence, short paragraph, or set of bullet points is all you need. For example, for an Item with this title,
Write operator delete if you write operator new.
I end this way (9 pages later, sigh):
Now, it's interesting to see how custom memory management routines can improve program performance, and it's worthwhile to see how such routines can be encapsulated inside a class like Pool, but let us not lose sight of the main point. That point is that operator new and operator delete need to work together, so if you write operator new, be sure to write operator delete, as well.
For the third edition of
Effective C++, I added a short list of bullet points to the end of each Item called "Things to Remember." That allowed me to eliminate the summary paragraphs from many Items while still allowing me to remind readers of each Item's most important information.
Item 9: Know how to modulate the stridency of Item titles.
Virtually every rule has exceptions, but some rules have more exceptions than others. The wording of your Item titles should reflect the likelihood that your readers will encounter exceptions. In real life, for example, we should (almost) always buckle up for safety, (almost) never drink and drive, and (typically) consider taking public transit when it is available. Those three words--
always,
never, and
consider--are three of the five words I've found useful when wording Item titles. Here's the full scale of advice urgency, from Always to Never:
- Always
- Prefer
- Consider
- Avoid
- Never
The default is "Always," so it's generally implicit. I could have worded one of the guidelines above this way, for example,
Always put Item titles in the imperative.
but "Always" here adds little, so there's no point in including it.
Because every rule has exceptions, there's an implicit "Almost" in front of any rule that begins with "Always" or "Never." However, including "Almost" in Item titles draws attention to the existence of the exceptions, and that's not what we want readers to focus on. For example, consider how wishy-washy this looks:
Almost always put Item titles in the imperative.
Please! Take a stand! That's one of the things that readers like about
Effective books: the authors give specific advice instead of bland platitudes. Each Item has a rationale, so any situation not covered by the rationale can naturally be interpreted as being an exception to the rule. Hence the implicit nature of "Almost."
Item 10: Cross reference liberally.
Effective books are collections of essays. Each is specific and constrained (see above), but collectively they cover a lot of territory. The territories they cover necessarily abut and overlap, and that means that almost no Item stands alone. When there are relationships among Items, readers need to know that. That's where Item cross-referencs come in. If Item A gives a detailed discussion of a topic that's relevant to Item B, B should probably have a cross-reference to A. (A might also have a cross-reference to B.) If Item A strengthens the rationale for Item B, B should probably have a reference to A. If Items A and B cover disjunctive situations, both should probably refer to one another (e.g., "Item A explains why you need to do X to achieve Y, but sometimes your goal isn't Y, it's Z. When that's the case, the advice in Item A fails to apply...").
In the end, most everything is related to everything else in some way or another. You don't need to point out all relationships to your readers (see above about omitting information they don't need to know), but you should definitely use cross references to point out the ones that are important in making effective use of whatever technology you are writing about.
Item 11: Minimize use of footnotes.
Footnotes make a book look more formal and academic.
Effective books tend to shoot for a more casual, informal approach. As a result, it's best to avoid footnotes whenever possible. In general, you'll find that information you want to footnote can either be eliminated or incorporated into the body of your discussion.
Item 12: Be consistent when referring to yourself and your readers.
This is a grammatical "person" issue: first person, second person, or third person? When you refer to the author of the book, do you say "I" (first person) or "the author" (third person)? When you refer to the reader of the book, do you say "you" (second person) or "the reader" (third person)? The choices are nowhere near as important as that you abide by them consistently. I like to envision
Effective books as one-on-one informal conversations between the author(s) and each reader, so I prefer using first person for the author and second person for the reader, e.g., "Now, when I say that XYZ is a good idea, I suspect you'll wonder if I'm off my rocker." Third person works, too, though I think it's stuffy: "When considering the author's recommendation to do XYZ, the reader may be forgiven for wondering if the author is off his rocker."
Bottom line: I see too many manuscripts where authors can't decide how to refer to themselves or their readers. Make the decision early on, write it down so you remember it, and adhere to it consistently.
Item 13: Seek out ruthless pre-publication reviewers.
No matter how careful you are, odds are that the book you write will contain errors or other problems. That being the case, it's in everybody's interest to find out about them as soon as possible. Ideally, you'll find out about them before the book is actually published, thus giving you a chance to fix them before your masterpiece is loosed on the world.
There are many ways to get good pre-pub feedback, but all have one thing in common: they are based on finding reviewers who are willing and able to tell you how your book can be improved and who don't pull punches. What you
want to hear is that your manuscript is wonderful and is ready for publication, but what you
need to hear is that some words are misspelled, some diagrams are confusing, some topics are technically incorrect, the way you've organized things makes no sense, and that you've failed to consider some aspects of the material that are important.
Providing such feedback is hard work, and that means that you're unlikely to find people willing to give it to you unless you go looking for them. Seek them out. Tell them you want to know
everything that is wrong with your manuscript. Make it clear that a better book is more important to you than an unbruised ego. Ask your friends to be reviewers only if (1) you believe they are willing to be brutal in their comments and (2) you honestly believe that your friendship can withstand the pressure. But don't rely only on your friends. Seek out individuals who are representative of your target audience, and ask them to tell you what they think. (Your friends are unlikely to be good at this. For one thing, there's a very good chance that your friends know more about what you're writing about than your average target readers does. After all, your friends hang out with you. Your readers don't.)
When I circulated an early draft of my second book, I got back comments from one reviewer who, having savaged the first 30-40 pages, concluded with "It doesn't get any better after that." It took me a couple of days to recover from that, but once I did, I was able to dispassionately evaluate the comments and conclude that they were accurate. Then
I rewrote the book, making extensive revisions. The resulting book was much better than it would have been had I received only comments telling me that this or that detail needed tweaking.
It's nice to hear nice things about what you've written. You're much more likely to hear them after your book comes out if you've heard awful things when the book is in progress. Seek out people who will tell you those awful things in advance so you won't have to hear them later.
2011 habe ich zum ersten Mal mein Seminar zum Thema die effektive Anwendung von C++ in Embedded Systems auf Deutsch gehalten. Das Seminar ist ziemlich gut gegangen, denke ich (niemand ist gestorben), aber nach dem Seminar war es mir klar, dass die deutsche Version des Seminars keine Vorteile im Vergleich zu der englischen Version hat, auch wenn die Teilnehmer aus deutschsprachigen Ländern kommen. Es scheint, dass die an diesem Thema interessierten Entwickler entweder kein Problem mit Englisch haben oder sie sogar eine Vorliebe für technische Seminare auf Englisch haben. Die erste Präsentation dieses Seminars war deshalb auch die letzte. 
