Nov
19
WRITTEN BY:
Mark Scott
Thursday, 19 November 2009
The way you write is a reflection of the way you think. That means (whether you like it or not) 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 or technical skills doesn’t always equate to good writing skills
Just because someone is a great project manager or is a business consultant extraordinaire, doesn't mean they're going to be equally expert at business or technical writing.
Yet, 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?
Your documents need to second guess your audience
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. Your documents need to provide all the information your audience 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.
Are you writing enough? Are your writing too much?
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. (I've heard, 'well at least it'll pass the weight test', one time too many.) 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.
Your document may end up in the hands of an unexpected audience: write for them
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.
What does your documentation say about you?
Your documents are evidence of your work and your ability. 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
|