The infinite monkey theorem states that a monkey hitting keys at random on a typewriter keyboard for an infinite amount of time will almost surely type a given text, such as the complete works of William Shakespeare. As such, it stands to reason that two monkeys would be able to produce the same volume of output, but are unlikely to write exactly the same thing. Add in a few more monkeys to the equation and suddenly you have lots of content, none of which really relates to anything else.

I’ll stop with the monkey metaphor before I insult anyone.

Consistency is an important part of communication, even at the simplest level of having a common terminology, using the same words consistently throughout a document helps the reader learn. Take this idea up a level, from a single document to a number of documents and maintaining the same terminology across all documents can further help re-enforce the messaging and aid learning, and should give the reader a level of comfort that the entire set of information has been thought of, and delivered, as a cohesive set.

Move up the stack one more time and you start to look around at surrounding areas of information, outside of product documentation, produced by a different department and it’s here that consistency starts to suffer.

Typically Technical Communications teams will spend some time developing their own Style Guide (however loose), and agree a basic set of terminology, also known as the Product Glossary. Having been involved with creating a Product Glossary in the past, it’s interesting that other areas of the company see it as being a ‘documentation thing’, until such times as you get them to sit down and help you compose entries for it.

I know that the information produced by my team will be consistent and is written in a similar enough style that it won’t ‘jar’ the reader. In other words, it doesn’t matter who wrote the information, it is all part of one larger set of documentation, with a similar tone, voice and style.

Aiming the information at the correct audience is a key part of deciding what the three attributes of tone, voice and style, should be, and it’s at this point that I find other departments starting to struggle. Without a clear idea of the audience, and with their own perception of what the message (the terminology) needs to be, there is a tendency to wander off message, and produce a document which, whilst perfectly good in isolation, doesn’t seem to fit into the overall set of product information.

So what type of information is this? Well it varies, and can be tracked through the customer (or company) journey and their interactions with your company and product. Broadly speaking there are four levels, all of which need to be talking to the correct audience, and ideally should be providing the same message in a consistent manner.

1. First up there is an introduction, a high level chat about our product and what it can do. This is typically a mix of marketing brochures, website collateral, and sales presentations.
2. The next level of interaction delves a little deeper into the business benefits and key selling points of the product, and can start to touch on product features and capabilities.
3. After that, there is a need to provide a level of technical information, outlining the architecture and fundamental design of your product, detail the full set of capabilities, and provide reassurance around any potential implementation issues that may arise.
4. And then we get to product documentation, training material, and ongoing support and maintenance information.

Four levels of information, all of which should be saying the same thing about the product, regardless of what message that is.

It would be wrong to say that each level is unique, as each interaction your company has with a customer will vary, but largely speaking the four levels allow anyone who is creating information to better understand their audience. Add in a Product Glossary to ensure terminology is consistent, and a strong product message and there is no reason why any of the content being produced cannot be consistent.

Mapping these levels to the amount of content available at each level gives us the following:

Of course this is a very simplistic model, but as a starting point, it at least provides the mechanism for anyone about to create new content to pause and consider the audience. So whilst you could add in several levels, and several different mappings of document types, I think it’s better to leave things a little open to question as that helps bring a better understanding of why the content is being produced in the first place.

I first introduced this model to my current company several months ago, and we are currently revisiting this to make sure it is still a good fit to our needs. The next step for me is beefing up our Product Glossary, and then we can get on with the thornier issue of document management, an intrinsic part of having a Content Strategy for your company.

How early do you get involved in a project? At the start? Part way through once the scope has been set? Or once the design has been agreed? Or do you swoop in at the end and document whatever you find?

One common complaint a lot of technical writers have is that they aren’t included early enough in lifecycle of a project. The downsides are that by the time work hits your desk you don’t have a full picture of who the customer is, why they want whatever it is you are building, and how they want it provided to them. All of which directly impacts the information being created.

So how do you, the lowly technical writer, make sure you are involved early in the project? By offering your services as a master information curator, task analysis guru and all round user advocate, that’s how!

During the early stages of most projects, there will be a period when the main requirements are gathered, ensuring the pain points are covered, and that the main scope of what you are building is agreed. A lot of those discussions are largely focussed on collating information from the heads of various subject matter experts (SMEs) and stakeholders, and gaining agreement on it in a singular form.

Sound familiar? I hope so, as it’s not all that far removed from discussing a new product feature with some of the guys who helped build it, and coming to a consensus on how it should be used and, therefore, how it should be documented.

As one of the core competencies of a technical writer, it’s something many of us have forgotten we do, largely because, hey, it’s just our job. However it takes a unique skill set, one that not everyone possesses, to be able to focus a number of different viewpoints into a cohesive story.

This type of work is often performed by a business analyst, but there is no reason why you can’t fulfill a similar role to some degree. The project team get the benefits of your skills, removing some of their early pain, and you get to be involved from the get-go. Win-win, right?

Well, almost. One caveat is that being involved in the early stages of a project is likely to overlap with the end of the previous one, so whilst you are wrapping up all those little issues (you know, unmentioned features and changes) you may struggle for time if you are also helping in the early stages of the next phase.

It’s a hard balance to find, but if you really want to get in early, and I think the benefits outweigh the downsides and if needs must you may need to get support from your boss to reschedule some work to free up your time to be involved. It’s a simple enough, progressive, argument:

Understanding the customer and the requirements leads to better information. Better information leads to better use of the product. Better use of the product, lowers support calls, leads to new product features and increased sales.

Which, I think, is a pretty powerful statement to make to your boss when you are asking to clear time in your schedule so you can start this cycle.

Last night, around 3am, I woke up. I lay there in bed wondering why I’d woken up and as my mind started to churn I realised I was very very awake.

In flooded four things I’ve been thinking about for some time, all of which are related but I couldn’t quite make the connection. Last night I cracked it. Maybe.

I’m still thinking it through but here are the four items in question:

1. Single sourcing our documentation – and recent discussions with other areas of the company who could benefit from the same approach.
2. Company Information Strategy – a simple pyramid based model that allows everyone creating content to ‘map’ their audience appropriately and which should start to help with consistency of terminology and messaging.
3. Document Management – there have been some murmurings about this from a few people and it’s likely to fall into my lap.
4. Requirements gathering – we’ve recently rolled out a new process which should lead to better requirements for each project build.

All of these are tied together, and if planned properly can feed off each other. Naturally there is quite a lot involved with all of the above and I’ll be revisiting items one and two in the coming weeks.

Ohh and I’ve still to pull together a slide deck on “selling our services”, which involves all of the above and more. Once it’s ready, I’ll share it here.

Exciting times ahead.

I honestly can’t remember the last time I picked up a user manual, an honest-to-god paper book of technical documentation. Actually that’s a lie, it was just last week when i was tidying up. I picked up several user manuals and moved them to a lower shelf on my bookcase.

It’s also been a long time since I last worked for a company that produce and printed user manuals but that’s more to do with my career path than any decisions I made within those companies.

Even now whilst we have a “documentation set” comprising several different user manuals, it’s published to PDF and made available as part of the product distribution (and also online).

So why do we still maintain this view of how information should be provided?

There is a level of comfort in having a table of contents and a structure to the information available when writing technical information. It allows you to make sure all the required information is in place, but most of the research I’ve read, and most of the anecdotal evidence I’ve heard, suggests that those lovingly created table of contents are not heavily used.

The index is another area, hell it’s another profession altogether, that we spend a lot of time crafting and rightly so as it is used by many people to navigate their way through a document.

But one thing that trumps both of these methods isn’t available in printed documents but is widely available for online information. Search.

OK, so none of what I’m saying is new, or revolutionary, far from it. Those of us who have been creating online help, regardless of the format (a lot of which was before the internet was popularised), know that if there is a search option available, it will be used.

With that in mind, and this is most definitely something we will be consulting with our users about, we are toying with the idea of dumping the index and the table of contents, making sure the content has a good set of internal reference links so users (power and novice alike) can find “paths” through the information, and switching the front page to be a Google-esque search.

Luckily we can pilot this approach whilst still producing the Javahelp, PDFs and HTML (Webhelp in Author-it terms) output so we don’t completely alienate our users. It’ll be interesting to see outcome.

Nobody really likes planning. Plans are bad in the eyes of many people, seen as a necessary evil by others and some people would rather just jump straight in and figure things out as they go along. However, if you approach them the right way, planning can provide more than just a set of deadlines. Specifically I’m talking about the type of Information Plan that is covered in Managing your Documentation Projects.

In that respect, plans are good. They help set the direction and make sure everyone knows what they need to do to get there.

Yup, plans are good. The creation of a plan usually drives discussion around the deliverables and the audience of the information.

It goes without saying then, and I’m sure you all agree that, and this is just in case you’ve missed my point, plans are good.

Unless you don’t revisit the plan throughout the project. At that point, through no fault of the plan, the plan is useless.

It’s very very easy to get sucked into the detail of your current work, understanding how to explain to users how Widget X works if you are running Component Y, and I’m as guilty of that as the next person. Revisiting your plan throughout the project will help keep you from losing sight of the woods for all those damn trees.

I have no idea what our users want.

I do know they want information, and I know they want that information to be kept up to date as our product evolves and as far as those basic needs are concerned, I’m happy that we are meeting them. Beyond that I admit I’m not really that sure.

Over the past couple of years we have plugged a lot of gaps and improved the documentation provided in key areas all whilst keeping up with new features being added to the product. We’ve moved to Author-it to give us the advantages of re-use and multi-format publishing and on the whole we’ve built a good reputation within the company.

So it’s time to take stock and look at the next area we need to improve and to do that we need to know what our users want.

On the one hand we are lucky in that we have access to a small number of them, and if we can arrange the time we can sit down with them and ask them direct questions. However there is a large portion of our audience that isn’t available to us and who we also need to converse with.

Rather than try and start up a conversation from cold, I’m thinking it would be a good idea to ask them to complete a short survey, the results of which we can discuss when appropriate.

But what to ask? In the past I’ve tried to get users to score the documentation on a number of criteria (who easy it was to find the information, if it answered their questions and so on) but that doesn’t really give much scope to start a conversation.

So I’ve been looking about for some examples and to my delight have found many. I’ll probably be picking and choosing questions from the following, but I thought I’d list them here in case anyone else finds them useful:

• Apple Logic Studio
• Solaris Developer Documentation
• Drupal Documentation Survey
• User Documentation Survey 2009

I’d also urge you all to take part in the last one, it’s relevant to us all.

Have you run user surveys? I’d love to hear your stories, successful or otherwise.

It’s funny how these things come together sometimes, when two separate discussions, one here in the office and the other in the Author-it Forums, nicely lead me to a conclusion on something I’ve been pondering recently. How to measure what we produce?

The first discussion was with a new guy in our team, who was voicing concerns about the amount of information he was producing. He stated that, when describing some of the concepts our product uses, he would spend a lot of time figuring them out, talking to people about them and understanding them, but that usually translated into “not a lot being produced”.

I pointed out that, as far as I’m concerned, the more concise and effective the information, the better. Some things do require a lot of content, others don’t. There are additional benefits when you consider the single source aspect as well, it’s much easier to re-use a tightly focussed topic than one which tries to cover too much information.

The second discussion, in the Author-it forums, was someone asking if there was a way to track the number of words each writer was producing, apparently as a way to track productivity.

Don’t worry, plenty of people pointed out the fallacy of that line of thinking; it’s very easy to pad out a document or topic with additional words even though they might not add any value and may lead to ambiguity.

However I’m not really thinking along the lines of productivity, nor measuring the individual, I’m more concerned with measuring what we produce.

But how?

The obvious answer is to engage with our audience and get their feedback about the documentation. There are various ways of doing this, and depending on your audience some might not be available.

Arranging time to sit down with the people who use the product, and your documentation, is best and can be run as a product focussed session. If your company runs customer forums or workshops then it should be easy enough to schedule time into the agenda (your company understands how important documentation is, right?), but even if you can’t get direct access you could try a questionnaire, allowing customers to ’score’ the documentation.

Ultimately you need to get feedback from the people who use your documentation, find out whether they can find the information they need, once they’ve found it do they understand it, is it clear, accurate, unambiguous? It’s not easy to quantify what we do at every level but using a questionnaire which includes an indication of a score can give you a way to start further discussions. The score itself isn’t the important bit, it’s what you do with the feedback that matters.

I’d love to hear if you’ve tried other ways of measuring your documentation, and I’m not alone. In the current economic climate there is more pressure to justify what we do, so making sure we have some good weapons up our sleeves will benefit us all.