Refactoring English

Effective Writing for Software Developers

by Michael Lynch

Many software developers think they’re naturally poor writers, but there’s no such thing.

Most software developers are weak writers because they don’t try.

You can improve your writing skills the same way you learned to become a better programmer: by learning best practices and understanding how to apply them.

Refactoring English will improve your writing in areas that matter most to developers, including:

  • Emails
  • Software documentation
  • Blog posts
  • Tutorials

I’m writing the book now, and it will be available as a digital download in 2025. Sign up below to receive updates and excerpts as soon as they’re available.

Book Contents

Refactoring English teaches everything I’ve learned over the years about applying effective writing techniques to the domain of software.

  1. Why Improve Your Writing?
  2. Get to the Point
  3. Make Your Writing Sound Natural
  4. Rules for Writing Software Tutorials
  5. Write Blog Posts that Developers Read
    1. You’re qualified to write a blog post
    2. Choosing topics
    3. Think one degree bigger
    4. Grab the reader’s attention
    5. Tell it like a story
    6. Plan a path to your readers
    7. Show more pictures
    8. Accomodate skimmers
  6. Find Customers through Blogging
  7. Write Effective Design Documents
  8. Write Useful Commit Messages
  9. Write Emails with Less Noise and Better Results
  10. Write Compelling Software Release Announcements
  11. Fine-Tune Your Writing
    1. Verbs drive the sentence
    2. Stay positive: how negative phrasing reduces readability
    3. Passive voice considered harmful
    4. Minimize cognitive load for the reader
    5. Brevity is performance optimization for writing
    6. Eliminate ambiguity and confusion
  12. Maintain Motivation
    1. Manage writer’s block
    2. Use a structured process to stay in flow state
    3. Editing: valuable because it’s hard
  13. Resources to Improve Your Writing
    1. Work with a professional editor
    2. Work with a professional illustrator
    3. Improve your grammar incrementally
    4. Using AI tools

Book cover design by Mohanvenkat Patta

Professional Sponsors

Individual Sponsors

Thanks so much to readers who financially supported the book early on!

Contact

Do you have questions about the book? Want to tell me about things you’re hoping to learn?

Get in touch! I’d love to hear from you.