Writing tips for developers
Use your refactoring skills to improve your writing.
Getting started
Sometimes, life gets in the way. That’s what happened with this site, which is not ready yet.
First, kudos to you for wanting to improve your writing skills. During the conference, I’ll be writing a reference of the topics covered by Refactoring: A Developer’s Guide to Writing Well and posting it here. Stay tuned.
In the meantime, you may find these books useful. I know I did.
Recommended reading
“If you want to be a writer, you must do two things above all others: read a lot and write a lot.” — Stephen King (On Writing)
Many good writers have written down their thoughts on how to write well. You and I have the privilege of mining their experience. There is no better way, so far as I know, to improve your writing. Read these books one at a time and as you read, apply what you learn when you write at work. Be playful and try something new.
If you are starting out, I would recommend reading in this order: (1) On Writing Well, (2) Made to Stick, (3) Technical Writing, (4) The Sense of Style. In between books, swap in Bird by Bird or On Writing for a tonal shift to explore the art and craft of writing.
- Bird by Bird – Anne Lamott
- Made To Stick – Chip Heath & Dan Heath
- On Writing Well – William Zinsser
- On Writing – Stephen King
- Refactoring – Martin Fowler
- The Elements of Style - Strunk & White
- The Sense of Style – Steven Pinker
- Technical Writing (6th edition) – John M. Lannon
Bird by Bird – Anne Lamott
shitty first drafts—KFKD radio—routines for writers
Anne Lamott is a wonderful writer whose book, Bird by Bird, made me want to write.
Her focus is on the daily reality of writing: the practice, the self-doubt, the joy. Though the book is geared for the aspiring novel writer and covers topics that likely won’t apply to your technical writing—characters, plots, and dialog—the parts about writing drafts, daily routine, and being kind to yourself make the book well worth reading.
Made To Stick – Chip Heath & Dan Heath
the curse of knowledge–keeping your reader—how to tell a story–making abstract concrete
You won’t find usage rules or principles of composition in this book because it’s not about the mechanics of writing. Rather, it’s about how to frame an idea. It focuses on how to break down a topic and sequence it for your reader.
On Writing Well – William Zinsser
clear writing == clear thinking—how to delete half your paragraph—clarity, simplicity, brevity, humanity
This book captures what it means to write well. Similar to Strunk & White, you’ll be introduced to the mechanics of writing: the rules to follow and the mistakes to avoid. But unlike Strunk & White, William Zinsser takes time to tell you the rules and explain why they matter.
At just under 100 pages, part one and two will give you practical tips to use in your everday writing. If you’re keen, you may find chapter 15 and 16—”Science & Technology” and “Business Writing,” respectively—to be worthwhile.
If you only read one book on writing, read this one.
On Writing – Stephen King
writing is telepathy—rewrite with the door open—read a lot and write a lot
One part writing, one part memoir. Stephen King takes you on a journey through his career and a few thing he learned along the way. Like Bird by Bird, this is geared towards novel writing but provides insights into day-to-day of writing well.
This one makes for a good audiobook.
Refactoring – Martin Fowler
code smells—refactorings—better code in tiny steps
This is not a book on writing but if you haven’t read it (or at least, leafed through it), you should. Even without this book, you have probably picked up the practice of refactoring. But, know this: there is no other place that so succinctly captures the practice. You will almost certainly learn something new.
At over 400 pages, it can feel like a textbook but you can get most of the value by reading only a hundred pages. First, read chapters 1 through 6. Next, keep the book nearby as you work. Anytime you find a code smell that tickles your memory, look it up. The book will point you to one or two refactorings that may solve your problem. Try it out. If it works, great. If not, try another one.
Soon, you’ll find yourself skipping the book and jumping right to better code.
The Elements of Style - Strunk & White
OG writing well
An ever popular book on writing. At less than one hundred pages, it is wafer thin and contains loads of useful tips for writing. Originally published in 1959, this book has been gone through four editions. Beware, the most recent is more than twenty years old and contains some outdated references.
If you’d like a more enjoyable read, I’d recommend On Writing Well over this book.
The Sense of Style – Steven Pinker
a window unto the world—arcs of coherence—avoiding professionalese
In this book, Steven Pinker explores how to write nonfiction that is worth reading. He explores topics that influence the shape of your work, like classic writing style, the curse of knowledge, and garden paths. Much of this book reads like a response to academic writing that is dense, uninteresting, or self-important. As an expert in your field, you may find it useful in making your work digestable to others. Each chapter can standalone so take your time.
You may find it hard to write the same after reading this book.
Technical Writing (6th edition) – John M. Lannon
efficient writing—speaking technically—every mistake you could make
This book picks up where On Writing Well and Strunk & White leave off. It dives deep into the mechanics of writing when you’re writing in the workplace. You’ll learn how to understand your audience, commnicate at the right level of complexity, and make your writing count.
At almost 700 pages, it is the longest book on this list but don’t let that deter you. Like Refactoring, a fraction of this book will give you much of the benefit. Read part one and part three leaf through the remainder.
I happened upon this book in my local library but there are likely other books on technical writing that would fit the bill too. Find one that fits you and go with it.