Further to my Too Simple post, and in response to the comment from Annie about the state of software manuals, I thought I’d try and give a bit of insight into the basic workings of my profession. Yes, that’s right I DO have a day job. I am a technical author and I write software documentation (actually I don’t like the “technical author” job title but that’s a different story).

Before I begin I’ll state that I’m not the most experienced technical author (there are people who have been doing this for 40 years), I’ve only ever worked in a software environment, and as in most professions there are a number of different methodologies and working practises which I can choose to follow. OK, caveat finished.

Ohhh and you may be wondering about the title of this post so let’s start there, how DO you make a cup of tea?

It’s a question I’ve used in a writing test (for graduate technical authors or those new to the profession) in the past, and it’s usually fairly effective at giving a rough first impression of how the candidate thinks in relation to product documentation.

Now, I’d warrant that most people reading this have some idea of how to make a cup of tea, but let’s presume that you didn’t, in fact, let’s presume that you haven’t even heard of tea. Starting to get a little tricky, isn’t it.

In response to my post, Annie specifically mentioned two very common errors in software manuals:

  1. The documentation is too technical.
  2. The documentation is not searchable.

The latter of these is inexcusable; whether it be the lack of an index, or a poorly created one, or whether the medium (PDF, HTML and so on) in which the manual has been presented hasn’t been made ‘search aware’, if the people using the documentation can’t find the information they need, the documentation has failed. There are many fixes to this problem, some of which can be driven by the user themselves, but I’m not going to discuss them here (I can in the future if you want).

Instead I’m going to focus on point 1, “The documentation is too technical”.

In this instance we are discussing software manuals written for basic computer usage and, as such, that gives us the first criteria within which we must consider the documentation. It is THE most important aspect that must be borne in mind when you are writing a software manual, namely “Who am I writing for?”. Once you start considering that you quickly get to “What do they know?” and the similar, but different, “What should they know?”. Of course you never fully know the technical knowledge level of each user of the documentation, so you learn what you can and make some informed presumptions.

With these considerations in mind, you can start to plan the manual for “How to make a cup of tea”. However before we can begin on the basic instructions we first have to make sure that the user knows what tea is, why it exists, why they might want to make a cup of it and where they are likely to find some. We may also have to explain similar details for the item that we are calling a cup, and further to that we may have to explain all the other required items answering all possible questions: what is a spoon? what is a kettle? how do I fill it with water? And so on.

Now, this could very easily become an exercise in futility, so at some point you realise you have to presume some knowledge on the part of the user. And it’s at this point the “curse of knowledge” kicks in, and where a lot of software documentation fails.

The Curse of Knowledge

Do you ever get exasperated trying to explain something to someone, something so basic that you can’t fathom why that person can’t get to grips with it, or for that matter why they don’t already know it? It’s likely that this is more profound in your work place, regardless of where you work. It’s in the midst of all this presumption that the phrase “there is no such thing as a stupid question” arises, a phrase which irks many, and downright baffles a few. If we presume no knowledge then the phrase holds true, but can we, SHOULD we, really presume that everyone else knows nothing?

Of course not, there is always a level of presumed knowledge, the curse comes along in deciding what that is and applying it consistently.

To get around this, some software companies write up full user personas, including names, photos, details of their life and experience, and from that you can start to extrapolate a level of basic knowledge. In our example, we have to presume the user knows about water, that it comes from a tap, and that you need to put it in a kettle to boil it (again, a lot of presumption is going on, even here. I presume that the user is standing in a kitchen, and already has a kettle to hand). We presume they know what tea is, what a cup and spoon are used for, and can perform simple manual tasks; filling the kettle, stirring the tea, adding milk etc etc.

I’m thirsty!

OK OK. Let’s make that cup of tea. Off you go, you know what to do, right?

Ohh good grief. Fine.

You will need a kettle, a cup, a spoon, a tea bag, milk and sugar (optional), and access to running water and a power point.

To make a cup of tea:
1. Fill a kettle with enough water to fill your cup. Tip: fill the cup and tip it into the kettle.
2. Put the kettle on to boil.
3. Place a teabag into your cup.
4. Once the kettle has boiled, add the hot water to the cup, leaving a gap of a few centimetres.
5. Stir and squeeze the teabag until you have a dark brown liquid. Remove the teabag at this point.
6. Add the milk in small amounts, and sugar if required, tasting as you go to check you will enjoy the finished beverage.
7. Stir.

Your cup of tea is now ready to drink. We suggest you open a pack of Jaffa cakes and enjoy one or two with your beverage.

Straight forward enough, right? However, I know that some of you would add the milk before the water, but that presumes you know how much milk to add. This method allows you to monitor the amount of milk as you go, over time the user will learn how much milk they enjoy and will probably adapt step 6 themselves.

Do you have a point?

Ummm… yeah, kinda.

In my previous post I suggested that you should learn the basics of something before tackling more complex tasks. In our example I’d get pretty pissed off if someone kept asking me where they should put the teabag (and I’d probably come up with a few other suggestions!), but if they wanted to discuss, say, how to make tea using tea leaves, then I’d know that they understood the basic process of making tea.

Of course it’s hard to adjust this example to something more complex, but if you flip things round it starts to be fairly easy to understand.

Writing a manual on how to make a cup of tea is absurd. It’s too simple. The flipside of that is that writing a manual for a highly technical and complex tool like a computer is very hard. There are too many levels of presumed knowledge to cope with, too many scenarios and possibilities to be able to cover them all. A lot of technical authors are guilty of taking the easy path, pitching the manual at a level of knowledge that isn’t too low so as to be endlessly repetitive and obvious, and not too high that it is only of use to the few individuals who can understand the information presented. We take a middle ground as much as possible, try not to exclude anyone by including information on our presumptions and covering as many “what ifs” as possible.

So maybe the manual isn’t too technical, maybe the user is just reading the wrong manual?

And I’ll stop there, as this could roll on and on; why are they reading that manual, is the title wrong? why doesn’t the manual they need exist? or does it and they just can’t find it? maybe it is the correct manual and they just can’t find the information they need? And so on and so forth. Regardless of the reason, it does mean that sometimes, occasionally, RTFM is the wrong thing to shout.