Revisiting the basics

There are some fundamentals tenets of our profession that are widely accepted. One being that you always need to know your audience before y can begin to understand their needs and so produce the information that they require.

The reason I mention this is because, whilst it’s something very basic and is deeply grained in the technical writer part of my brain, I keep forgetting it.

Let me explain.

I’m currently working on a mini-project aimed at making sure the language we use and the things we talk about through all levels of our product information (from the website and marketing brochures, down to the lowest level of reference information) tell a consistent story. From basic facts and terminology to the concepts we need to convey, it’s important that everyone throughout our company talks about things the same way.

As such we’ve modelled the information into four layers with each layer (roughly) representing a broad layer of user and information types. These types match our engagement model and will allow other areas of the company to understand not only what information is required but, most importantly, WHO the information is for.

I’m writing up a summary document (covering two of the four layers) which will cover the main areas of the product and what language and terms we want to use. The document also outlines the basic concepts of our product, and for each concept describes the level of information expected. This will allow others to build specific documents at the appropriate level, focussed on the correct user type, using the correct language and terminology.

The trouble is that I’ve really been struggling to get my head around it and I was finding it very hard to write the descriptions for each conceptual area. I was mentioning this to a colleague earlier and that’s when it struck me.

I’d forgotten who I was writing for.

The summary document is aimed at internal staff, but is covering the information likely to be required by two different types of reader/layer. As I’ve been developing this information I’d lost sight of that and was trying to write one piece of information for two very different types of user.

So, I’ve decided to split the summary document into two, one for each type of reader and I’m already finding it much easier to structure the information accordingly.

I know I’m not alone when it comes to this kind of thing, that it’s very easy to become blinkered to everything else when you zero in on a particular task. I’ve been working fairly closely with a colleague on this but hadn’t spoken to her for a few days and, without that check in place, I’d started to lose sight of the big picture.

And yes, I know this isn’t rocket science, but hope it may serve as a timely reminder to others or at least let you learn from my mistakes.


  1. Timely indeed, Gordon. Thank you very much. In my case it wasn’t so much a reminder, but it confirmed a point that came up in a discussion among colleagues yesterday.

    I also would like to emphasize the disconnect between problem and solution, symptom and cure that I find quite common. As you say, your document somehow didn’t work, but the problem (as I understand) was not the actual writing or the structure, but a poorly defined audience. At other times, it may be a poorly defined purpose that makes documentation difficult to write or maintain.

  2. Gordon,

    I run into the same problem from time to time. Using conditional text or conditional tags helps me keep track of that content when using a tool like MadCap Flare or RH.

    In fact, I’m trying to figure out an easy way to do conditional tagging on audio for podcast and/or full audio for eLearning presentations. I think the best practice I’ve found for that is over on Articulate’s blog where they recommend using a Notes tab listed as ‘Transcript’.

    — Charles

  3. Is this shift in tense acceptable in any form of writing?

    “The trouble is that I’ve really been struggling to get my head around it and I was finding it very hard to write the descriptions for each conceptual area.”

Comments are closed.

%d bloggers like this: