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.
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:
The more you separate these stages, the better the result. The next sections give more detail about each stage.
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:
This will help you decide:
Once you know exactly why you’re writing, it’s easier to know what to write (and what not to).
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:
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.
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:
For some quick feedback, copy/paste your text here: http://www.hemingwayapp.com/
I’d love to hear if you found this helpful. Have a question or comment? Leave it below!