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:

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

Send me updates on Refactoring English

Receive updates and sample chapters as I write the book.

Unsubscribe anytime.

Book Contents

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

  1. Introduction
    • Why improve your writing?
    • Most developers write poorly because they don't try
    • How this book will help you
  2. Verbs Drive the Sentence
    • Verbs liven up technical writing
    • Replace nouns with verbs
    • Swap boring verbs with better ones
  3. Stay Positive: How Negative Phrasing Reduces Readability
    • Readers don't like writers when you don't write in the affirmative
    • Turn a negative into a positive
  4. Passive Voice Considered Terrible
    • Recognize the passive voice
    • Out with the passive, in with the active
    • The few cases where passive voice is useful
  5. Brevity Increases Your Value Per Word
    • Brevity is performance optimization for your writing
    • Easy deletions that improve brevity
  6. Create a Compelling Hook
    • Hooks tell the reader if your writing is worth their time
    • How to hook your reader early
  7. Why So Serious? Make Your Writing Sound Natural
    • Why formal writing sucks
    • Red flags of excessively formal language
  8. Consider Your Audience
    • A few missing words can lose you 90% of your audience
    • Avoid jargon
    • Speak at the right level of abstraction
    • Create different sections for different audiences
  9. Accommodate Skimmers
    • Skimmable writing indicates strong structure
    • Make your writing skimmable
  10. The Writing Process
    • Pre-writing, writing, and editing
    • Effective processes save time and decrease misery
    • A writing process for people who hate writing
  11. Editing
    • Rearchitect with structural editing
    • Refactor with sentence-level editing
    • Cut the fluff
    • Create a personal writing checklist
  1. Manage Writer's Block
    • Create a habit of writing
    • Tackle non-creative writing tasks when you're blocked
  2. Common Writing Pitfalls for Developers
    • Maintain parallelism
    • Stay consistent
  3. Mind Your Grammar
    • Does grammar matter to programmers?
    • Tools for checking grammar
  4. Work with a Professional Editor
    • Editors save you time and money
    • How a freelance editor improved my writing
  5. Work with a Professional Illustrator
    • Readers respond positively to writing with visual elements
    • How to find a freelance illustrator
    • How I work with my illustrator
    • Make your own visuals
  6. Write Better Emails
    • Choose your length wisely
    • The longer the email, the more diligence you need
    • Does this need to be an email at all?
  7. Write Better Design Documents
    • Design docs waste time when you write them poorly
    • How to organize a design doc
  8. Write Better Blog Posts
    • Develop a unique writing voice
    • You don't have to be an expert to write a blog post
    • Common blogging mistakes
  9. Write Better Tutorials
    • The elements of a useful tutorial
    • Read your tutorial as your target reader
  10. Tools for Writing
    • What to look for in writing tools
    • The best tool is useless unless you're writing
    • My writing toolset
  11. Continuous Improvement
    • Improve your writing whenever you read
    • Excellent writing resources for developers