I’ve learned the hard way that writing is… hard. But anyone can become a great writer by following a few rules.
This post is a collection of guidelines I’ve adopted while writing four technical books, publishing countless blogs, and enduring the wrath of frontpage Hacker News commentary. Many of these rules were imparted by the great mentors I’ve had over the years, such as Brian Hogan (Pragmatic Bookshelf editor) and Jon Mountjoy (creator of Heroku’s DevCenter).
Make every word count.
Write with the door closed, rewrite with the door open
Writing requires concentration, but editing requires feedback. When it’s time to write, close the door, turn off alerts, and remove distractions. When your first draft is complete, share it with people–friends, colleagues, reviewers–and listen to what they say.
Use the right word
Richard Feynman once told a story about a group of physicists explaining “acoustic reverberations” to a confused non-scientist. Feynman interjected, saying “it’s an echo”.
Precise word choice is important, but longer isn’t always better. Unusual vocabulary words and technical jargon distract readers from your point. In general:
- Don’t “utilize” something when you can “use” it.
- Don’t “procure” something when you can “buy” it
- Don’t “ascertain” something when you can “learn” it
Show it, don’t say it
Avoid the word “easy” in your writing. If something is easy it will go without saying. More importantly, if readers find something difficult, you may alienate them by calling it easy. Avoid “simple” or “straightforward”, too.
Cut and paste
When you write, you’re telling a story. When you rewrite, you’re removing all the parts that are not the story. Be ruthless as you edit. Cut and move sections like Victor Frankenstein piecing together his creature.
Bring your reader with you
Some pronouns will engage your readers, while others distance you from them.
- Don’t say “I find it important to”, when you mean “You should”
- Don’t say “It is widely believed”, when you mean “I think”
- Don’t say “I’ll show you how”, when you mean “We’ll see how”
I use you/your in this post because I want you to adopt these rules. But if I were writing a tutorial and guiding you on a journey, I might use we/us/ours to indicate that I’m in it with you. It’s sometimes acceptable to switch between we/us/our and you/your in a single piece of writing, but in general you want to pick a voice and stick with those pronouns.
Throw the first one away
In The Mythical Man Month, Fred Brooks warns software developers that their first version of code will have bugs, run slowly, and lack features. You’ll likely need to rewrite it. The same caution applies when writing prose. Plan to throw your first draft away. You’re going to make mistakes; might as well make them quickly and get on to the second draft.
Write, write, write
Writing is a muscle. Practice your writing, share it with people, and learn from their feedback. Like going to the gym, it’s not easy. You’ll need to create a writing schedule and set goals. Will you publish one blog post a month? Will you write a post this year that gets one-thousand views? Aim high.
Know your craft
Writing is a craft, which means there’s always more to learn. There are many more rules I could have included in this post, like “prefer the active voice”, “avoid noun stacks”, “use action verbs”, and “use puncuation effectively”. But then I’d be writing a fifth book. Instead, I encourage you to read some of the wonderful resources I’ve used over the years:
- Dave Thomas’ So You Want to Write a Book series
- Keys to Great Writing by Stephen Wilbers
- On Writing by Stephen King
- On Writing Well by William Zinsser
Break the rules
Writing isn’t a science. There’s a time to break the rules, but do so cautiously.