My Rules for Writing Well

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).

Be concise

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:

Break the rules

Writing isn’t a science. There’s a time to break the rules, but do so cautiously.