Chapter 7: Editing and Technical Review

Writing the first draft is the hard part. Editing is what makes it good. Most technical books go through multiple rounds of editing, each with a different focus. This chapter covers the editing process and how to get effective feedback from reviewers.

Why Editing Matters More Than You Think

The difference between an average technical book and an excellent one is almost never the content — it is the clarity. Both books might cover the same topics with the same depth. The excellent one is simply easier to follow, because it went through rigorous editing.

Your first draft captures your knowledge. Editing makes that knowledge accessible to someone who doesn’t share your context.

The Editing Passes

Plan for at least three distinct editing passes. Each pass has a different focus, and mixing concerns leads to poor results.

Pass 1: Structural Editing

Read the entire manuscript from start to finish. Ignore grammar, word choice, and code formatting. Focus on:

Flow: Does the book progress logically from one chapter to the next?
Gaps: Are there concepts the reader needs that you never explained?
Redundancy: Do you explain the same thing in multiple places? Consolidate.
Pacing: Are some chapters too dense while others feel thin?
Dependencies: Does any chapter reference a concept not yet introduced?

This is the pass where you move, merge, split, and delete entire sections. It is the most disruptive edit and must come first.

Pass 2: Content Editing

Go chapter by chapter. Focus on:

Explanations: Are they clear to someone who doesn’t already understand the concept? Read your explanations as if you are encountering the topic for the first time.
Examples: Do they illustrate the concept effectively? Are they self-contained enough to understand?
Transitions: Does each section flow into the next? Does each chapter end in a way that motivates the next?
Tone: Is the writing consistently in your chosen voice? Are there sections that are unexpectedly formal, casual, or condescending?
Accuracy: Are all technical claims correct? Are there outdated references?

Pass 3: Line Editing

Now focus on the sentence level:

Remove filler words: “very,” “really,” “basically,” “actually,” “simply,” “just.”
Eliminate passive voice where active voice is clearer.
Cut unnecessary qualifiers: “It’s important to note that…” — just state the thing.
Fix grammar, punctuation, and spelling.
Ensure consistent terminology: if you called it a “service” in Chapter 3, don’t call it a “module” in Chapter 7 unless you explicitly note the distinction.
Check that all cross-references (chapter and section numbers) are correct.

Self-Editing Techniques

Read Aloud

Reading your text aloud is the single most effective self-editing technique. Your ear catches awkwardness, repetition, and unclear phrasing that your eye skips over. If you stumble while reading a sentence aloud, the reader will stumble too.

Change the Medium

If you wrote on a computer, print the chapter and edit on paper. If you wrote in one text editor, read in a different one, or export to PDF. Changing the visual presentation helps you see the text with fresh eyes.

Time Distance

Put a chapter aside for at least a week before editing it. When you read it again, you will see problems that were invisible when the text was fresh in your mind.

Read as Your Reader

Mentally adopt your reader persona from Chapter 1. Read the text as Maria the backend developer, not as yourself. Where would Maria be confused? What would she skip? What would frustrate her?

Search for Your Crutches

Every writer has crutch words and phrases. Search your manuscript for them. Common technical writing crutches:

“Basically” — rarely adds meaning. Delete it.
“Simply” / “just” — implies the concept is easy, which can alienate confused readers.
“Obviously” / “clearly” — if it were obvious, you wouldn’t need to write it.
“In order to” — replace with “to.”
“It should be noted that” — delete and state the thing directly.

Technical Review

Why You Need Technical Reviewers

You are too close to your material to evaluate it objectively. You know what you meant to write, so you see that meaning even when the text doesn’t convey it. Technical reviewers see what you actually wrote.

Choosing Reviewers

Recruit 3-5 technical reviewers with these profiles:

Subject matter expert (1-2 people): Someone who knows the topic deeply. They catch technical errors, outdated practices, and missing nuances. They are not your target reader — they are your accuracy check.
Target audience member (2-3 people): Someone who matches your reader persona. They tell you where explanations are unclear, where they get lost, and where they lose interest. Their feedback is the most valuable for improving your book.
Writing-focused reviewer (1 person, optional): Someone who reads a lot and can give feedback on prose quality, pacing, and readability. This person does not need to be technical.

Giving Review Instructions

Don’t just send your manuscript and say “let me know what you think.” Give reviewers specific guidance:

“Please focus on:

Are the explanations clear? Mark any place where you had to re-read something or felt confused.

Do the code examples work on your machine?

Is there anything you expected to find that’s missing?

Is there anything you would skip?

Don’t worry about typos or grammar — I’ll handle those in a later pass.”

Managing Feedback

You will receive contradictory feedback. One reviewer says Chapter 5 is too detailed; another says it isn’t detailed enough. This is normal.

Rules for handling feedback:

If multiple reviewers flag the same issue, fix it. Consensus problems are real problems.
If one reviewer flags an issue and others don’t, use your judgment. Consider whether the reviewer matches your target audience.
You don’t have to implement every suggestion. Thank every reviewer, consider every point, but make the final decision yourself.
Track all feedback in one place. A spreadsheet with columns for chapter, feedback, source, and status works well.

The Feedback Sandwich

When a reviewer points out a problem, resist the urge to defend your writing. They are doing you a favor. Thank them, understand the underlying issue, and fix it. If their suggested fix doesn’t work, find a different solution to the same problem.

Code Review

Code in a technical book deserves its own review process.

Automated Checks

Run a linter on all code examples.
Run all tests.
Build the example project from scratch on a clean machine.
Verify that all commands produce the claimed output.

Manual Code Review

Have a developer (not you) read through the code examples and try to follow them. They should:

Run every example.
Flag code that is confusing without the surrounding text.
Note any inconsistencies between code in different chapters.
Check that variable names, function names, and conventions are consistent.

Proofreading

After all other editing is complete, do one final proofread. This is different from line editing — it catches the small things:

Typos and misspellings.
Incorrect cross-references.
Broken links (in digital formats).
Formatting inconsistencies (indentation, heading levels, code block formatting).
Missing or duplicated words (“the the”).

Consider hiring a professional proofreader. They are inexpensive relative to the effort of writing a book, and they catch things you will miss.

Key Takeaways

Edit in multiple distinct passes: structural, content, then line editing.
Read your text aloud — it catches problems you will miss reading silently.
Put time distance between writing and editing.
Recruit reviewers from different perspectives: experts, target readers, and writing critics.
Give reviewers specific instructions for what feedback you need.
When multiple reviewers flag the same issue, fix it.
Code examples need their own review process: automated checks plus manual review.
Proofread last, after all substantive editing is complete.

← Chapter 6: Diagrams, Visuals, and Formatting

Table of Contents

Chapter 8: Tools and Workflow →

Gaëlle Candel