The way you write is a reflection of the way you think. That means your documentation affects people’s perception of your ability. The cleverness of your work can be diluted and even lost if it’s not matched by top-quality documentation.

 

I’ve read, reviewed and edited enough documentation to have seen this time and again.

 

And you know what? It really doesn't take that much extra effort to make a good document a great one. The trouble is getting to ‘good’—this is where many people seem to struggle. Having great business and technical skills doesn’t always mean good writing skills. 

 

But how can we hope to successfully consult, plan, design, build, test, manage, operate and do all the other things we do within business and ICT project and operation environments, without putting finger to keyboard to record what we’re doing or planning on doing? And how do we ensure that nothing gets lost in transcription?

 

When you’re explaining something to someone, you’re using many different visual and verbal clues to determine whether you’re being understood, and you adjust your information and delivery accordingly. Documents don’t have the advantage of that dynamic interaction. Your documents need to second guess your audience and provide all the information they may need, without being asked for it.

 

This may sound obvious, but the quality of some documentation I’ve seen tells me that it’s not.

 

Technical documents, in particular, can be a challenge to read and understand.  We'd be a lot better at writing them if we thought about them in terms of taking our readers on a journey. Don't just drop your readers into the story, reveal it to them.

 

We need to write enough to address the needs of our audience, and we need to write to engage them. And forget about any perceived weight-test. A document doesn’t require bulk to be meaningful or useful. It reminds me of that urban myth about the university philosophy exam question, 'Why?', and how most people wrote reams in response, but one person got full marks with the answer, 'Why not?' How many n-hundred word essays have you written without depending on filler to achieve the word count?

 

We’re all busy. We don’t have time for reading waffle.

 

You’ve probably worked closely with a number of people in order to prepare your documentation, but don’t write it for them. Write it for the people you’ve never met, who may one day pick up the document and depend on it to make a decision or to perform a task. You need to tell them the story so they are able to fully comprehend it … without the benefit of having been involved in the process or having you to answer questions.

 

Think about it: in some cases the documentation you produce may be the only evidence of whatever it is you've done. So, what impact do you want to make with your documentation?

2 COMMENTS SO FAR...

RE: Lost in transcription Great post, Mark! I especially like your advice about taking readers on a journey when we write. Far too often, writers don't think about the end user/reader and write only what makes sense from their own perspective. This is a great reminder. BY Kathryn Lee ON   Saturday, 28 August 2010

RE: Lost in transcription Thanks for the feedback, Kathryn. This post of yours has great, complementary tips: www.acceleratedbr.com/blog/dot-the-i%C2%B4s-and-cross-the-t%C2%B4s-quality-writing-is-crucial/ BY Mark Scott ON   Saturday, 28 August 2010

YOUR NAME:
Your website:
TITLE:
COMMENT:
SECURITY CODE ENTER THE CODE SHOWN ABOVE IN THE BOX BELOW
ADD COMMENT   CANCEL