A writer is someone for whom writing is more difficult than it is for other people.
— Thomas Mann, Essays of Three Decades

Do you find writing software documentation painful? You’re not alone. But writing is a necessary part of any job. Ideas need words to travel; you can’t collaborate without writing.

For many developers, the pain of writing comes from not knowing where to start. Or where to stop. Or how to do the bits in between.

If you’re one of them, this guide may help.

Write in three stages

Writing needn’t be complicated. I’m not going to teach you some elaborate methodology. But it helps if you approach it in three stages:

1. Plan
   Choose your audience. Who are they? What do they need to know? What do they already know?
2. Write
   Put Words On Paper. Nothing more, nothing less.
3. Edit
   Make bad text into good text. Remove useless words, leave useful words.

The more you separate these stages, the better the result. The next sections give more detail about each stage. 

1. Plan

Planning isn’t about writing an outline of your text. Yes, some writers prefer to list all their points in bullets before they start writing. Many don’t. They make up the structure as they go along. Whichever approach works for you is fine and you should try both at least once. The main thing is knowing your audience. Who are they? What do they need?

Try completing these statements:

• I’m writing this for _______^{(group of people)} who want to _______^{(activity or goal)}.
• They already know _______, but they don’t know _______. 
• They care about _______, but they don’t care about _______.
• They’ll read this when they’re _______^{(activity or state)} in/at _______^(place). 

This will help you decide:

• What to include
• What not to include
• What format or medium is best

For example:

• If you’re writing a detailed technical essay for military pilots about World War 2 airplane maneuvers, don’t include Germany’s invasion of Poland. 
• If you’re writing an installation guide for an IntelliJ plugin, don’t spend 200 words explaining what IntelliJ is.
• And if you’re writing a maintenance handbook for underwater machinery, don’t publish it as an HTML website.

Once you know exactly why you’re writing, it’s easier to know what to write (and what not to).

2. Write

The first draft of anything is sh*t.
— Ernest Hemingway

The second stage is simple, but tough. The goal: Put Words On Paper.

This is tough because most people have an inner critic that won’t shut up. It’s constantly telling them to fix their last sentence, instead of write their next one. This makes writing slow and painful.

Don’t listen to the critic. It thinks it’s helping, but it’s not. Instead, remember these things: 

• Bad writing > no writing. The point here is not to write well; it’s only to get the ideas out of your head and on the page. By all means, write badly. You’ll have plenty of time to make it good later.
• You don’t have to start at the beginning. Just because your text will be read from top to bottom, doesn’t mean it must be written that way. Start anywhere. Jump around all you want. Many great writers do.

Again, your job is to cover white space with words. Keep doing that, and soon you’ll have the material you need for the next stage.

3. Edit

A sculptor made a beautiful marble statue of an elephant.
An admirer asked, “How did you do that?”
The sculptor said, “Easy. I took a block of marble and I cut away everything that didn’t look like an elephant.”

The editing stage is where the real magic happens. All writing is bad before editing.

When you read a text that really flows, you may imagine that’s how it was written, too. Inspiration striking the author like lightning and—eureka!—the words come pouring like water. But that’s rarely how it works.

Writing isn’t linear, but iterative. You write and then you edit, edit, edit. Good writing usually starts as a terrible draft with, if you’re lucky, some promising passages. It doesn’t get good until you edit. Luckily, that’s the fun part! So get the writing done quickly and move on to editing.

How do you edit? Mostly, you remove things that are non-essential. Sometimes, you add things that were missing. Spend 80% of your time doing the first, 20% the second. Look for these things:

• Unnecessary words (really, actually, very)
• Hesitation words (a little, kind of, somewhat)
• Missing connections (add: because, but, also)
• Sentences that describe an action, but not who performs the action (passive voice)
• Information that’s irrelevant for your audience (check your plan from stage 1!)

For some quick feedback, copy/paste your text here: http://www.hemingwayapp.com/

Tell me what you think

I’d love to hear if you found this helpful. Have a question or comment? Leave it below!

About the author

Wouter Veeken        

I'm a technical writer from Boxtel in the Netherlands. I enjoy the books of Terry Pratchett, the music of Paul Simon, and playing the guitar.