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:

The documentation is too technical.

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.

Comments (26)

Interesting stuff. This is probably why O’Reilly manuals are so successful – they’ve found a level of expertise and (generally) stick to it.

btw, you neglected to mention that the water needs to be above the minimum level in the kettle else overheating may occur. If the kettle has a visible element a single cup of water is often not enough. Further to this a certain amount of the water will escape as steam during the boiling process and spillage can occur on pouring, especially when suffering caffeine withdrawal, so I find a cup and a half does the job, ensuring you end up with the requisite amount of tea.

Writing a non-fiction book is much the same. You constantly find yourself asking the question “do I assume that a person who picked up a book on this subject will already know this, or should I explain it to them.” And more importantly (because I’m betting everybody at some point or other has been irked by authors getting this one wrong), “I explained this earlier in the book, but it may be days, weeks or even months since my reader read that bit, and he may have forgotten by now. Should I explain it again?”

Pete – see, I missed a basic and crucial information because I presumed the person would know that.

Alan – the advantage ‘manuals’ have over fiction is that we can treat information in isolation. Presume the reader has just opened the book at section X and give them everything they need to complete their task (based on the fact that users only open the manual when they are stuck).

mike – no way! I’ve seen the IBM writing style guide, it’s a monster. I often wonder how their authors get anything done, must spend more time conforming to writing standards than actually writing! On the other hand, they DID give the world DITA… but that’s a different post (for a different place!)

RyanJanuary 31st, 2007 at 9:14 am

Hi Gordon, Sorry to be a pain (and slightly off topic), but when did you change the feeds to be snippets and not full posts? It’s better for us feed reader types to see everything without leaving the comfort of google reader.

My point (again): the instructions you gave conflicted with that knowledge – do we fill up the kettle with one cup or to the minimum level mark? Which do we choose? Your instructions needed a use case to make sure that the actual command was something along the lines of “use one cup of water for cup of tea required; if the kettle has a minimum level mark and the water is below that level, top it up”

So tell me: how did you learn to use a computer? Did you read a manual before you switched it on? Did you go to classes? Did you just jump in and start playing?

OK. The example given is not complete, but I really wasn’t going to:
a. spend more than 10 minutes writing up a blog post
b. actually write out the instructions in full – I could easily fill 5 or 6 pages to do that!

And my Dad taught me how to use a computer, alongwith computer magazines at the time – twas a BBC Micro (and Mac Plus at one stage too). Yes, he did go through the basics with me, how to switch it on, how to use the keyboard and mouse and so on. That plateau allowed me to continue to learn on my own without fear of breaking anything. Well not much…

There are people who put milk in first?!? Are you freakin’ kidding me?!? The world’s going to hell. Fascinating stuff though. Tell me, what does a ‘Creative Writer’ do at your company? I saw a vacancy there recently.

As long as the people who put milk in first don’t make me a cup of tea, I don’t mind…

***************
I was going to apply for a job as a technical author recently, because although I’m techie in some ways, I think I can see things from the user’s perspective. Plus, I love writing system documentation (when I’m given the opportunity to do so), as odd as that may sound…

Also bear in mind when cursing the author that you might not be reading the manual in the source language, that the translator may or may not have had much to work with and all suggestions to the large blankety blank Japanese monolith providing the “English” source fall on deaf ears. Not that I’m speaking from experience or anything…

Great post Gordon. I did a short (8 week?) tech writing course many years ago somewhere in East London and our first assignment was to write the instructions for erecting a wooden fence. Hardest thing I’ve ever done.

Oh and on the rare occasions that I slum it with teabag tea, I’m in the *gasp* teabag+milk then hot water camp. Makes a damn fine cup of tea. But not as good as a pot of leaf tea. Ah, but again the milk in before or after argument rears its ugly head. Didn’t George Orwell write the definitive guide? Must have a search.

Well, I fall back on my cub scout training when we had to make tea for sponsorship or something. (Hey, it was more than 2 years ago – I can’t be expected to remember. I haven’t upgraded my internal RAM yet!) It distinctly said, milk before tea. I never kept it but the sponsor form had instructions on it including the whole thing about swilling hot water around the pot first.

These days I’m a coffee drinker.

jaypegFebruary 1st, 2007 at 2:07 pm

I find the fact that you advocate squeezing the teabag frankly quite distressing, that way lies bitter tannin bad dreams. No, the dreams!

1. Fill a utensil with enough water to fill your cup.
2. Put the utensil on to boil.
3. Once the water has boiled,add sugar.
4. Add tea.
5. Add half-cup milk.
6. Add a pinch of pepper.
7. Boil until you have a dark brown liquid.
8. Pour the tea in the cup.