Chapter 4: Writing and Editing
If you have identified your audience, and you know what problem you are trying to help them solve, then it remains only to "put the right words in the right order." Of course, this is the challenge, and it's more work than most people imagine.
This chapter provides a relatively detailed description of the writing-editing-revision cycle we expect your book to go through.
Working with Your Editor
At many other publishing houses, your proposal is evaluated and your contract is negotiated by an "acquisitions editor," who also calls you from time to time to inquire about progress, and perhaps even takes you out to lunch--but never does any actual editing. When your manuscript is complete, it is edited (copyedited, really) by someone you've never met. The job of delivering a satisfactory manuscript is left entirely up to you. (One of our competitors confided that only about 30% of the books they sign are actually delivered by the authors.)
At O'Reilly, by contrast, your editor will be intimately involved with every step of the process--in some cases, acting almost as a co-author.
The last thing we want to see from you is a completed manuscript. That's right: the last thing. After your proposal; the next thing we want to see is a sample chapter, which your editor will read very carefully. (By the way, if you aren't sure about which tools you want to use to write the book or you have questions about how to use them, see Chapter Two.) You'll get back detailed comments about your style and approach, questions about the technology you're describing, and recommendations for how to improve your work.
If the comments are light, you might then go right on to the next chapter. But if there are significant problems, you may be expected to rewrite the chapter--perhaps several times--until you and the editor are both satisfied.
Here are some of the things the editor will be looking for:
Obviously, in order for the editor to make these determinations, the chapter needs to be a substantial one--or perhaps the job might require several chapters, if your book includes several different types of material (such as tutorial and reference sections in the same book). At any rate, you would be advised to tackle some of the most difficult material first, so that you can work out problems early.
Be sure to revisit your schedule after you have some actual writing under your belt. You may find the version submitted with your proposal to be hopelessly optimistic or right on target. In either case, you should take the time to re-evaluate it, so we can schedule the book "rollout" more effectively.
After you've come to agreement with the editor on your sample chapters, you can get on with the rest of the book. However, you should plan on continuing to submit material to the editor on a chapter-by-chapter basis. If all goes well, the editor's comments should be lighter and more positive on each succeeding chapter.
You may find, however, that as you write succeeding chapters, you may need to go back and revise earlier ones. Despite careful work on each chapter, you and the editor may still need to make a complete pass through the book to "pull together" the complete first draft.
One thing to look forward to: it's at this point that you typically receive your second advance payment.
Once you've completed the first draft, it's time for technical review. We make an effort to have the book read both by technical experts on the subject and by those just trying to learn about it. (In many cases, our editors are good examples of the latter class of reader. They probably have some prior knowledge of the subject of your book, but presumably have learned as they go along.)
It is important that the draft sent out to technical reviewers be substantially free of formatting errors, typos, and other "nits." Even if reviewers are warned not to pay attention to such things, we've found that their comments will end up concentrating on cosmetic rather than substantive defects.
If we think that your book will be of interest to our corporate resellers, we'll try to find technical reviewers at those companies, since early exposure to the book might help their purchasing decisions. In addition, they may provide comments about specialized needs of their company that might not only improve the book, but will make it more salable to their customers.
We also have contacts with people who've reviewed books for us in the past (including our other authors).
However, you are the best source of technical reviewers for your book. You should know the names of people who are knowledgeable about your subject. You can approach them directly, or can pass along suggestions to your editor. Generally, we look for no fewer than three and no more than five technical reviewers. We pay a small honorarium (or free books) for completed technical reviews.
Friends and colleagues are also a useful resource, but we generally expect you to use them as informal reviewers of preliminary drafts, since they lack the distance to provide us with an completely objective technical review.
Dealing with Review Comments
Once the technical review comments come back, you find what kind of a job you have on your hands. Comments may range from nitpicking to abuse!
We generally ask the reviewers to send a short letter to the editor, outlining the general tenor of the review comments, and to send the detailed markup directly to you. You should plan on talking over the comments with the editor (especially if you don't agree with them!), and may need to copy the editor on specific comments, so you can develop a strategy for dealing with any controversial issues.
Be honest with yourself. If a reviewer tells you that your approach is all wrong, and deep-down you know that she's right, buckle down and rewrite the book (or the offending part) from scratch. You'll find that your work was not wasted; a complete rewrite will often go more quickly than an attempt to patch a bad job.
Talk with your editor about the extent of the changes, and the best way for the editor to review them. If the changes are significant, it may be easier for the editor to re-read the revised version completely. But if the changes are minor, the editor might be grateful for a copy with change bars. (If you are using troff, you can insert .mc requests manually, or can use diffmk to generate a copy showing the differences between two versions.)
(Speaking of differences between versions...if you are doing many versions of your book, with heavy back and forth between you and the editor, you might do well to use a revision control system to keep track of each draft.)
If you disagree with a reviewer about a technical point, don't automatically break the tie in your own favor. Check with the other technical reviewers, or perhaps even seek new ones.
Also, don't hesitate to ask the original reviewer for more information!
Your Final Draft
After you've revised the book to include all review comments, you should make sure you're happy with every detail before submitting your final copy. We've had no end of trouble with late changes submitted after the production department has begun developing the final camera-ready copy for your book. (See Chapter 5 for additional details.)
Your final draft should include an index. Because our production department will help you with the index, that topic is covered in the next chapter.