Over the last 18 months or so I’ve had the great experience of reviewing a handful of books in various stages of development. In doing so I noted several patterns that emerged and captured them here. Enjoy!
Make sample code stand-alone test cases
Whether you are developing Python or PowerBuilder, chances are there is a unit-test framework available. Leverage these frameworks in creating your samples. It forces discipline upon the author to keep examples small and self-contained. More significantly, it provides code that will compile and be immediately useful to readers.
Never underestimate the power of copy and paste.
Develop reader personas
Writers face the challenge of crystallizing target readers. What is their level of education? What is their experience with the subject being presented? More importantly, writers face the less obvious question: Who are they not writing for? Poor attention to these questions manifests itself in the form of inconsistencies like: assuming the reader understands the quicksort algorithm but in the previous chapter explaining how to download and unzip a file.
Borrow a technique from the design world to mitigate this challenge: Develop full-blown personas of your readers. Include photos. Include a work-history. Is this the type of person who wants to go home at 5PM or understand the subject from the inside out? What is their reading style? Make a few copies. Hang them on the wall where you write. Send them to your editors.
Mercilessly challenge yourself: Is this something the readers already know? Is this something readers need additional foundation on?
Define your value proposition
Odds are, your book is not the only one on the subject. In the planning stages of the book define your value proposition in clear terms. Send it to your editors. What does your book bring to the party that no other does? Does it consider common pitfalls? Does it describe internal implementation details? Is it aimed specifically at beginners or advanced readers? Is it a comprehensive treatise on a subject?
Struggling to come up with your value proposition? Maybe the project isn’t such a great idea.
Consider various styles of reading
A small minority of your readers will make a front-to-back consideration of your manuscript. More readers look for answers to a specific problem. Still more read in an exploratory style, seeking an overall survey or looking for topics that interest them. Ask yourself: How do I serve these various types of readers? Devices such as “Best Practices” or “Pitfalls” beak-out boxes help capture the attention of explorers. A topical Q&A summary can serve the answer seekers.
Think about the guy at Borders flipping through your book on a rainy afternoon. Remember the frantic developer spilling cold coffee on your book as he works on solving a problem with a production system.
JUnit In Action
Head First Design Patterns
“Don’t be too pleased with yourself.”
This one is borrowed from the style guide provided to writers of the Economist magazine. The idea’s relevance to programmers is emphasized in Larry Wall’s consideration of great virtues a programmer. In it he defines “Hubris” as:
“Excessive pride, the sort of thing Zeus zaps you for. Also the quality that makes you write (and maintain) programs that other people won’t want to say bad things about. Hence, the third great virtue of a programmer. See also laziness and impatience. (p.607)”
Self-confidence is a good thing; leave it unchecked and you will endear yourself to few readers. For whatever reasons, the industry breeds excessive self-assurance. Challenge yourself: Can use of the first person singular be reduced? Better yet, eliminated entirely? Do you see phrases like: “A naive programmer would…” or “Inexperienced users might…”?
Respect your reader; they could probably teach you a thing or two.
Leave your fingerprints on the manuscript
This is the corollary to “Don’t be too pleased with yourself”. Without being self-serving let your unique voice be heard. You represent a unique intersection of experience, education and ideas. Let this individuality come through. Have you been consulting for years and seen techniques succeed or fail. Tell readers about it! Have a relevant war story? Share it! Inject some personality; relentlessly combat a dry documentary style.
If you are not consciously battling tedium, you have ceded to it.
Use a single problem domain for sample code
Don’t be seduced by metasyntactic variables. Pick a realistic problem domain and stick to it. Don’t switch from stock quotes in the first chapter to class scheduling in the second. Let your reader reap the benefits of investing time in understanding the problem domain. Note: This is not to say examples should be cumulative and dependent on prior chapters.
Allow them to focus on the message and not the means to convey it.
Hibernate: A Developer’s Notebook
Metasyntactic Variables
Say more by saying less
Keep your language simple and eliminate digressions. Simple words are the most powerful. “It was the best times, it was the worst of times…”. “In the beginning…”. “We didn’t land on Plymouth Rock…” Unsparingly revise long and wordy sentences. Watch some DVD commentaries and listen to directors wax-nostalgic about scenes they deleted in the interest of producing a better film. Learn from them. Don’t make your book the next Ishtar. Unsympathetically delete sentences, paragraphs and chapters.
You’ve got work to do if you can’t remember the last time you simplified a sentence or deleted a portion of your manuscript.
Cite other works
Citations reinforce the hard work that went into the manuscript. More importantly they show readers where more can be learned on a specific topic. Subscribe to O'Reilly’s Safari service. Spend some time at a good book store. Work with your publisher to get copies of books they publish on related topics.
Unix System Administration Book
Code Complete
Communicate compromises
Every technology represents a series of compromises. Communicate these to the reader. Don’t make them learn the hard way. This isn’t a hammer for every nail. This isn’t a solution to every problem. Challenge yourself when outlining a topic: What are the relative merits the implementation? What were the alternatives? When should this technology not be employed? What would my readers benefit most for knowing?
Prove to your reader you’re not a zealot.
Effective XML ( particularly items 24,25,41 )