21 August 2011

Getting started: step 1, what are you writing about?

I'm sometimes asked what the first steps are in writing ‘good’ documentation... where to start. My answer is usually that you need to have clear answers to four vital questions... what you are writing about, who is going to read it, why are you writing it and why are your readers reading it.

These are only a starting point, and I’m going to take each one in turn, although you need to combine the answers to them all and not act on one in isolation.

First, what you’re writing about. People often think this is the ‘obvious’ question. There’s the software/product/service – just write about it!

But I believe you need to dig a little deeper. Some topics are so huge that you need to narrow down the scope or you’ll drown in information. Others so diverse that you could be looking at it from a completely different perspective to the person who’s asked you to do the work.

Imagine that you are asked to write about the way a company documents its products(a common enough scenario). You could look at this in a number of different ways:

  • The documents that accompany each product (user guides, reference manuals, tutorials, training materials, online help) and guidance on what goes in each.
  • The applications and tools that are used for the various types of document - and possibly instructions on their use or the methods that have been adopted.
  • Typographical, stylistic, naming and other conventions, helping writers to conform to the brand identity of the organization.
  • The review process, and how updates are handled.
  • Language guides to aid translation or understanding by non-native speakers.

And these are just a few that have occured to me while writing this!

So when someone asks me to ‘write about X’ something, one of my first questions is always to find out ‘What about X?’

Next, we'll look at step 2 – who is going to be reading it?