Chapter 11: Maintaining and Updating Your Book
A technical book is not finished when you publish it. Technologies change, APIs evolve, best practices shift. A book that was accurate on release day can become misleading within a year. Maintaining your book is part of the commitment you make to your readers.
Why Maintenance Matters
Outdated technical books are worse than no book at all. A reader who follows outdated instructions encounters errors, loses time, and loses trust. If your book tells someone to use a deprecated API, you are actively harming them.
Maintenance protects:
- Your readers: They get accurate, working information.
- Your reputation: An up-to-date book shows you care about quality.
- Your revenue: Updated books continue to sell. Stale books get bad reviews and stop selling.
Types of Changes
Errata
Errors discovered after publication: typos, incorrect code, wrong output, inaccurate claims. These are the highest priority to fix.
- Maintain a public errata page (on your website or GitHub repository) so readers can check for known issues.
- Fix errata in digital editions as quickly as possible.
- For print editions, publish an errata list and incorporate fixes in the next printing.
Compatibility Updates
The technology you wrote about releases a new version. Your code examples may break. Configuration options may change. Commands may behave differently.
- Subscribe to release announcements for every technology your book covers.
- When a new version is released, test all code examples against it.
- If breaking changes affect your book, update the relevant chapters and note the change.
Content Additions
The ecosystem evolves and new capabilities, patterns, or tools become important. You may want to add:
- New sections within existing chapters.
- Entirely new chapters.
- Updated recommendations that replace previous advice.
Content Removal
Sometimes the right update is deletion. If a tool or practice you recommended has been superseded or deprecated, remove or replace the relevant content. Keeping it in misleads readers.
Planning for Maintenance
From the Start
Build maintainability into your writing process from day one:
- Pin versions: State which versions you used and pin dependencies in your code repository.
- Automate testing: CI that runs all code examples catches breakages before readers encounter them.
- Track dependencies: Keep a list of every external technology, library, and tool your book depends on.
- Modular structure: Write chapters so they can be updated independently without cascading changes throughout the book.
A Maintenance Schedule
Set a regular schedule for maintenance:
- Monthly: Check for errata reports. Review the issue tracker if your book is on GitHub.
- Quarterly: Run all code examples. Check for minor version updates to dependencies.
- Annually or on major releases: Evaluate whether the book needs a substantive update. Test against major version changes.
Versioning Your Book
Minor Updates
Small fixes (typos, minor code corrections, clarifications) can be published as updates to the current edition. In digital formats, readers may get the update automatically (Leanpub) or need to re-download.
Maintain a changelog so readers can see what changed.
New Editions
A new edition is warranted when changes are substantial enough that the book is meaningfully different from the previous version. Common triggers:
- A major version release of the primary technology (e.g., Python 2 to Python 3, React 17 to React 18).
- Fundamental changes in best practices.
- More than 30-40% of the content needs rewriting.
A new edition is also a marketing event (see Chapter 10). It generates fresh attention and sales.
Communicating Changes to Readers
- Update your landing page and description to note the edition and what’s new.
- If you have a mailing list, notify subscribers of significant updates.
- On platforms like Leanpub, publish release notes with each update.
- On your errata page, note which edition each erratum applies to.
Managing Reader Feedback
Channels
Make it easy for readers to report issues:
- A GitHub repository with Issues enabled.
- An email address in the book’s preface.
- A feedback form on your website.
Triage
Not all feedback requires action:
- Bug reports (broken code, incorrect information): Fix promptly.
- Suggestions (new topics, alternative approaches): Evaluate for future updates.
- Questions (confusion about content): Consider whether the text is unclear and needs revision.
- Scope requests (“you should also cover X”): Usually out of scope for the current edition, but note for future editions.
Responding to Feedback
Always respond to reader feedback, even if the answer is “that’s outside the book’s scope.” Readers who feel heard become advocates. Readers who feel ignored become detractors.
The Second Edition Decision
At some point, you face a decision: invest in a second edition or let the book wind down.
Signals That a Second Edition Is Worthwhile
- The book still sells, but reviews mention it being outdated.
- The underlying technology has changed substantially.
- You have accumulated a long list of improvements.
- Readers still ask questions and engage with the material.
Signals That It May Be Time to Move On
- The technology the book covers has been largely replaced.
- Sales have declined to a trickle with no signs of recovery.
- You have lost interest in the topic.
- Someone else has published a more comprehensive or up-to-date book.
There is no shame in letting a book reach the end of its useful life. All technical books are, to some degree, ephemeral. What matters is that the book served its readers well while it was current.
The Living Book Model
Some authors adopt a “living book” model: the book is never “done” and is continuously updated. This works best with:
- Self-publishing platforms that support updates (Leanpub, Gumroad).
- A subscription or membership model for revenue.
- A small, focused scope that is manageable to maintain.
The living book model is demanding but produces the most up-to-date resource possible. It works well for fast-moving technologies where a traditional edition cycle is too slow.
Key Takeaways
- Technical books need ongoing maintenance to remain accurate and useful.
- Build maintainability in from the start: pin versions, automate tests, keep a dependency list.
- Set a regular maintenance schedule: monthly for errata, quarterly for code testing, annually for substantive review.
- Publish errata promptly and communicate changes to readers.
- Make it easy for readers to report issues.
- Decide between minor updates and new editions based on the scope of changes.
- Know when to invest in a second edition and when to let a book reach the end of its life.