article

Drowning between the tags

Documents are about getting thoughts out of one head and into another. Good documents achieve this, bad documents don't. It works like this:

The big arrow in the middle is the bit that most people concentrate on: the way in which the document gets from one person to another. This involves document tagging, formatting, transmission, storage, searching, retrieval, printing and so on. But in truth, that's the easy bit.

Here are the two hard bits:

I'm going to talk about the writing bit first, and the content bit second. By the end of this talk, I will have introduced you to a way that you can improve the content of your documents.

One of the problems is the way in which the document is actually written - the words and phrases that are used. Look at this beautifully laid out slide:

Subject has ownership of ovine juvenile
Back covering has high reflectivity
Random-walk path approximates subject's trajectory
The lamb was sure to go

This slide is wonderfully laid out (it should be - I did it myself). It uses animation, colour and graphics. But there's one problem with it - the first three lines are meaningless. The words are all wrong, and this is hard problem number one for documentation.

This is hard to control, but there are a number of ways of doing it. I won't dwell on these, but here are some of them anyway:

Style guides: A style guide is a book that tells you what words and grammar to use. The most widely used worldwide is the Chicago Manual of Style, published by the University of Chicago. It's got all sorts of stuff in it:

Part 1 Bookmaking
1 The Parts of a Book
2 Manuscript Preparation and Copyediting
3 Proofs
4 Rights and Permissions

Part 2 Style
5 Punctuation
6 Spelling and Distinctive Treatment of Words
7 Names and Terms
8 Numbers
9 Foreign Languages in Type
10 Quotations
11 Illustrations, Captions, and Legends
12 Tables
13 Mathematics in Type
14 Abbreviations
15 Documentation 1: Notes and Bibliographies
16 Documentation 2: Author-Date Citations and Reference Lists
17 Indexes

Part 3 Production and Printing
18 Design and Typography
19 Composition, Printing, Binding, and Papermaking

The major problem is that it's about American English, rather than Australian English. The equivalent work in Australia is the Australian Government Printing Service "Style Manual", which covers the same kind of ground.

Style guides work well when you have the time to learn them. In an organisation with low staff turnover and dedicated writers, this might be the case. But in most organisations style guides are just too hard to find and use.

'Paint by numbers' methodologies: Methodologies that constrain how people write are many, but perhaps the best known is Information Mapping, which was invented by Robert Horn sometime just after the second World War. Information Mapping is about fitting what you want to say into one of seven possible word structures. It's the word equivalent of paint by numbers.

Horn has gone on to bigger and better things: such as the invention of a communications methodology based on pictures combined with words. Here's a slide from his web site:

I hope to hear all of these comments from my audience as we go along.

Another structured approach is START, which constrains people to writing one page of text and one diagram per 'topic'. Information Mapping and START have in common the idea of 'chunking', which restricts the amount of text that you write about a particular idea. Chunking is not a city in China.

The problem with these kinds of approach is that they give you the impression that you are solving the problem, without actually making a difference. It is of course quite possible to write material using START or Information Mapping which is complete gibberish. And people who write gibberish without these methodologies don't tend to suddenly produce clear prose with them.

Controlled languages: Controlled languages take a different approach, by restricting the vocabulary (and in some cases also the grammar) that you use. Here's a partial word list of 'Basic English':

a able about account acid across act addition adjustment advertisement after again against agreement air all almost among amount amusement and angle angry animal answer ant any apparatus apple approval arch argument arm army art as at attack attempt attention attraction authority automatic awake

The idea is that since you use only a subset of English, what you write is easier to read (particularly for non-English-speakers) and easier to translate.

Of course, learning to use a restricted vocabulary is hard, particularly when there's a restricted grammar to learn as well. But if you have the time and the energy, the results can be quite impressive.

Editing: The most common way of controlling the writing process is called 'editing'. Newspapers and other regular publications have to maintain consistency across the various bits of text that make them up - it would be annoying for a reader to see "NSW" in one story and "N.S.W." in another next to it. So newspapers use (as well as style guides) a hierarchical system of editors who check and recheck all of the incoming material and generally push it into a coherent style.

The same kind of process is used in large technical documentation projects, which may have this structure:

Project manager/Editor
Writer 1
Writer 2
Writer 3

Or even this one:

Project manager
Editor
Writer 1
Writer 2
Writer 3

This is all fascinating (I hope!) but is still only nibbling away at the problem. After all, even if you have the writing perfect and the transmission perfect, how do you control whether your documents are actually covering the ground that you need.

Consider for a moment the following scenario: we're in a bank. A customer phones and speaks to a customer support rep. The customer asks for the current interest rates for term deposits, and the CSR starts reading them a list of interest rates (different rates for different periods and different amounts on deposit) from the bank intranet page.

"No," says the customer, "can't you just email it to me." The CSR takes down their email address and promises to look into it.

This particular CSR has never attached a document to an email before. But they hit the F1 key on their email software and read the help there about how to attach a document.

Fine so far. Now they have to figure out how to save an HTML page from their intranet onto their desktop so they can attach it. They press the F1 key on their browser and that tells them how to do that.

Fine. Now they notice that the intranet page (in fact, every intranet page) has a bit at the bottom that states that it's commercial in confidence. So they have to find out if it's okay to email it to a customer.

They turn and talk to the CSR next to them, who says they don't know the answer. So the CSR gets up and walks over to their supervisor, who says they don't know. The supervisor calls the bank's public affairs office, but no-one answers the phone. They leave a message. The original CSR sends the customer an email saying that they're not sure whether they can release the information. The customer has by this time already spoken to another bank, and has decided to deal with them instead.

Now, let's look at this as a documentation problem. The intranet uses all of the latest technology: the page that they are viewing is XML, with embedded JavaScript and all of the bells and whistles. The screen they are viewing it on is a flat-screen plasma device. The intranet page containing the interest rates is updated every day automatically from the bank's mainframe using JavaSprockets.

If anyone is wondering what JavaSprockets are, I made that bit up.

The help text for the email client and the browser are both written by expert technical writers, using the latest in tools and writing methodologies. The information is chunked into readable segments, and is searchable using a natural language interface. All of the information that the user needs in order to drive the software is contained in the help, and it's accessible and readable.

But we lost the customer. So what went wrong?

The answer is that the content of the documentation that the rep used was wrong. It provided partial answers to the question, but:

left out vital information
provided the information in four unrelated pieces (interest rates, browser, email client, public affairs office)

Let's leave the bank for a minute and look at the solutions to the 'content' part of our problem.

There are basically only two of them: standard headings, and audience and task analysis.

Document standardisation started with the US military during the second world war. That was the first war in which a whole bunch of conscripts (people with basic training) got to play with some fairly complex machinery under somewhat difficult conditions. It made sense to have all of the documents with pretty much the same structure, because someone who was familiar with one document could move to another and find their way round in it.

For example chapter 8 has to cover preventative maintenance (oiling, checking, and so on) so a conscript who knows this can quickly find the preventative maintenance chapter in a manual for a sten gun, or a helicopter, or whatever. I remember working in a miliary project and having to put in a chapter about preventative maintenance - but for a piece of software. You don’t oil software.

The other problem with this approach is that it doesn’t actually make documents better. If we try to apply this approach to the problem of the bank customer service rep, we might think about having a standard set of headings for each intranet page, maybe like this:

Page content
Copyright notice
How to email this page to a customer

That doesn't really make sense. After all, there are a zillion things you might want to do with the page, including printing it, changing it, reporting an error on it, or deciding whether to read it every morning.

Standard headings are much used and much failed. They give the impression that you are controlling content, but generally don't solve the problem.

So much for standard headings.

Now, having shown why each other method won't work, we're down to our last hope. As I mentioned earlier, this is called audience and task analysis. It works like this.

First, figure out who the 'audiences' are for the documentation. In the bank customer rep case, there is only one: a bank customer rep. If you were looking more widely at the problem, you'd have multiple audiences: tellers, customer service reps, bank managers, intranet developers, etc.

Then figure out what business tasks the person has to carry out. In this case, some of them might be:

Customer Service Representative
Fill out timesheet
Answer incoming phone call
Send material to customers

Of course, there would be more than these, but they will suffice for the moment. Having figured out the audiences and tasks, you then work out what information the audience will need in order to perform the task.

At this point, we're looking at a customer rep, who wants to send material to customers. Armed with this information, we can think about all of the various problems and opportunities that might come up as part of this task. The material might have to be mailed, or emailed, or handed over the counter. The material might have to be photocopied, or downloaded and saved from the intranet, or it might be a brochure. Whatever the context, analysing the requirements down into an audience and a task puts the whole thing into perspective.

The most important aspect of all of this is that 'audience' and 'task' are two pieces of information which are known to the user at the point they need the documentation (sometimes they are the only pieces of information). The customer service rep knows that they are a customer service rep. They also know that they want to send some material to a customer. So if the document is structured by audience and task, they can find what they want.

Look instead at what happens if you take the same information and structure it in any old 'logical' way:

Using the browser
Using the email client
Copyright on bank materials
How to use the phone system
Being polite to customers
Who to ask for more information

Look familiar? If you don't use audience and task as your sort criteria, then you end up with a set of documents that have holes in them, and that provide the rest of the information in (for the reader, in the context of what they're trying to do) a confusing jumble.

Now audience and task analysis is not a proprietary methodology that you have to pay to learn. It's actually in the public domain, in the form of an Australian Standard: AS4598. It's also due to be published as an International (ISO) Standard sometime in the next year.

AS4598 explains what audience and task analysis is about, and is written like a textbook, with lots of hints and tips. Actually, it's made up of two older British Standards published under one cover.

And if you want to make sure that whoever you've subcontracted your writing to is using audience and task analysis, you can specify another Australian Standard: AS4258, something like this:

Clause 42. Documentation. Documentation shall be to Australian Standard AS4258.

This magical NCFD ("number containing four digits") is a contractually-binding document which forces the subcontractor to properly plan the documentation using audience and task analysis, and have that plan signed off by you before they start writing.

I hope you found all of that interesting. Now here's the sponsor's message ... the company I work for, HCi, uses these standards for all of its work. Every single piece of documentation planning that we do complies with these standards, because we've found that anything else just plain doesn't work.

Although audience and task analysis was designed primarily for user documentation, we use it for all of the kinds of content that we develop:

user documentation and help
training materials
policies and procedures
software design capture/reverse engineering

The point I'm making is that audience and task analysis is not restricted to the development of user documentation, which is what most people use it for now.

Let me come back to the point I started from:

Documents are about getting thoughts out of one head and into another. Good documents achieve this, bad documents don't. And the difference between a good and a bad document is what goes <between>the tags</between>. And a powerful way to control that is by using audience and task analysis.

back to ARTICLES Etc Contents
to HCi Services