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:

  • Does the chapter tell the reader what he or she needs to know? Is it accurate, complete, and useful? In sum, does it work?

  • Is the treatment appropriate to the audience? If it assumes prior knowledge, does it tell the reader clearly about those assumptions?

  • How readable is the chapter? In a well-written book, the words seem to disappear, and the reader is gripped directly by the concepts. In a poorly-written book, the words are an obstacle; comprehension is slow and painful. In short, the book must be engaging and interesting. (To a technical reader, of course, "interesting" most often means: tells me what I need to know as efficiently as possible.)

  • How well organized is the chapter? One of the nicest things a customer ever said about one of our books was: "Every time I had a question, the answer was in the next paragraph." If the author has done the work of thinking through the subject, and puts everything in the right order, the reader finds even difficult concepts easy to understand. Proper organization may mean eliminating unnecessary detail, clarifying assumptions, or identifying the most direct "flow" through the required information.

  • Does the chapter make good use of figures, tables, and examples? Many authors have a tendency to leave figures to the last minute, which generally means that they are fewer and of poorer quality than if they'd been developed as an integral part of the presentation. Figures typically are screen dumps (which should be made from working examples) or line drawings. Line drawings can be simple pencil sketches, or can be developed using computer tools, if you like. Our graphics department will most likely redraft them in any case.

  • Are there alternate ways to present material more effectively? For example, a topic that is interesting but breaks the flow of the narrative might be recast as a sidebar.

  • Are there common grammatical mistakes that can be caught early (so they don't need to be fixed later on by a copy editor)? Are there infelicities of style that the author should be vigilant against?

  • Does the chapter demonstrate knowledge of and adherence to O'Reilly's conventions? While we expect every book to be somewhat different, a key part of our marketing strategy for many books is to give them a "brand identity" that readers can rely on. As a result, after you sign the contract, we'll send you out a style guide that offers specific advice about structure and organization, about our macros, and about the conventions we follow and the literary devices we use in our books. Your first chapter will give the editor a chance to review these conventions with you, figure out which ones are appropriate and which inappropriate, and what distinctive features your book might have that will require development of new conventions.

  • Does the chapter use its terminology consistently? The editor will teach you "style sheet" techniques used by copy editors that will help you to remember how you've used various terms.

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.

Technical Review

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.

Locating Reviewers

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.

Go back to Table of Contents.
Go back to Chapter 3.
Go forward to Chapter 5.