Some organisations simply have nothing written down before we start working with them. They tend to envision that we’ll produce some sort of ‘magic manual’ that will fix all of their documentation problems. This is wrong on so many levels, but how do you explain it to the client?

Here’s a way that works. Draw a picture like the one below - it’s a chart in which one axis represents the length of time for which the intended audience has had a relationship with your client, the organisation you’re writing for - in this example we’ve labelled the two extremes as ‘pre-sales’ and ‘post-sales’. The other axis presents a view of  the spectrum of audience types - in this case from management to technical people.

Now you can start to talk with stakeholders, and map out where proposed documents actually live on the diagram. For example, on the following version, we’ve identified where we think a set of API-related technical documentation should live, together with a marketing brochure and a technical datasheet.

In all of this, we’re obeying the golden rule - any document can only address at most one of the small red sectors plus its immediate neighbours. If a client suggests that you write for an audience that includes everyone from senior management to the downright technical, you can draw a diagram like the one below and show him/her that the scope is wrong.

The more focused an audience, the more a piece of writing can do the job properly - the magic manual above is trying to do too many jobs for too many people, and will fail miserably.

Obviously, the diagram can be customised to your own circumstances, but it’s proved to be useful in many projects, from writing specialised marketing literature to documenting event-driven APIs for embedded hardware.

This entry was posted on Tuesday, June 24th, 2008 at 3:44 pm and is filed under Writing. You can follow any responses to this entry through the RSS 2.0 feed. Both comments and pings are currently closed.