Documentation standards mean more work for technical writers

This is the text of a talk given by Phil Cohen at the Australian Society for Technical Communications conference in Sydney in 1999.

Of course, as writers you will notice immediately that there are two possible implications that you can draw from the title of this talk.

The first is that documentation standards (and I’ll explain what I mean by them in a minute) are a pain in the asterisk, and that in order to produce the same amount of documentation, technical writers will simply have to work harder. Documentation standards are dead weight hung around the neck of the writer, to slow you down, drag you to the bottom, make your life a misery and generally spoil your day.

The second implication is that standards will create more jobs for writers, and that they will open up new opportunities for technical writers to get involved in the development of documentation that would otherwise not be done at all, or be done by others. So standards make the future broader and brighter for technical writers.

Well are documentation standards a good thing, or a bad thing? Before I answer that question, let me tell you what I mean by documentation standards.

There are three categories of standards:

• product standards - these are things that tell you what to write, or how to lay a document out, or how to bind it
• process standards - these are things that tell you how to plan, or how to manage or estimate or assess it
• quality standards - these are things that tell you how to make sure that you’re following your process and product standards

I’ll look at each kind of standard in turn.

Product standards

Examples of product standards for documentation are:

• military specifications that tell you how wide your margins have to be
• templates that tell you what headings to use in a document
• national standards that tell you what to put in a document, like IEEE1063

When you buy a fire extinguisher, you’ll see that it’s got a mark on the side that tells you that it complies with a particular Australian Standard. That’s a product standard - it tells you that the fire extinguisher was made of a particular material, in a particular way.

Are documentation product standards a good thing? Well, that depends.

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 content, because someone who was familiar with one document could move to another and find their way round in it.

For example, if there’s a standard that says that chapter 8 has to cover preventative maintenance (oiling, checking, and so on) then a conscript who knows this can quickly find the preventative maintenance chapter in a manual for a sten gun, or a helicopter, or whatever.

The military also likes things to be neat (because war is such a messy business) and so they like have all of their typography the same. They also like to specify things like paper whiteness and ink colour - both to make all of their documents look neat, and also to make sure that they’re readable in the field. They also like to specify sentence structure, including things like whether you put a comma before the last element of a list.

There are a couple of problems with specifying things like chapter headings and ink colour.

The problem with specifying ink colour or paper whiteness is that it means increasing costs. Why? Because it costs money for the customer (the military) to think about how to specify ink colour, which colour to specify, and to write this as a specification that the supplier can’t get around.

And it costs money for the supplier to figure out what the specification means, and to find ink of the required blackness, and then to test the blackness of the ink once it’s been printed (and some specifications call for testing as well). And if it costs the supplier, guess who pays? The customer.

The same can be said of specifying margin width, or where to put the commas. These can increase costs as well.

Is it worth it? That depends on whether the cost of not having the specification outweighs the cost of having it. You’ve got to ask yourself the question whether putting that extra comma in the list is actually going to make a difference to anyone except the person who came up with the specification.

Chapter headings are another issue. I remember in a miliary project once having to put in a chapter about preventative maintenance - but for a piece of software. You don’t oil software. So the chapter read: "Chapter 8: Preventative maintenance - none". That despite the fact that each chapter had to have an expensively-printed card insert.

The ‘specified chapter heading’ turns up in other contexts as well. It’s common to find templates used these days for everything from user documentation to standards themselves. It’s a very widely-used approach. When someone wants to make sure that a document covers a particular subject, or that it meets a particular need, they specify the table of contents.

Unfortunately, there’s a problem with this approach: it doesn’t work. Let’s say you want to make sure that every quality system document used in your organisation meets the needs of its readers. The general approach is to set out the headings that must be used, like this:

• Introduction
• Glossary
• Purpose
• Prerequisites
• Procedure
• Document control information

This list is generated by someone sitting down and imaging a list of headings (or more likely, copying a list from a document they’ve seen somewhere else). The first time you come to use a list of headings like this, one of two things will happen:

• you’ll find that you’ve got nothing to put under one or more headings, or
• you’ll find that you need more, or different headings

For example, if you haven’t used any specialist terms, you won’t need the ‘Glossary’ heading at all. And if you’re writing a document more than 5 or so pages long, you’ll need some subheadings as well. It may be that there’s no procedure in the document at all, but instead there’s a huge table of values. The standard lets you add appendices, so you end up with a blank ‘Procedure’ heading and an appendix containing the guts of the document.

The other problem with this approach is that it doesn’t actually make documents better. I guess that’s not strictly true: if you happened to write a document big enough to need a glossary, and you would otherwise have forgotten to put one in, having a ‘Glossary’ heading might prompt you to put one in. But generally, specifying the headings for a document does not ensure that it will meet the needs of the reader.

So to summarise, there are a number of things that you might find in a documentation product standard:

• specifications of layout, colour, etc
• specified forms of English
• specified headings to use

Do these make more work for technical communicators? You bet they do. But it’s work of the ‘bad’ kind: more work for the same amount of documentation.

That’s not to say that one shouldn’t have product standards for documentation - only that you should realise that the more you specify, the greater the cost, and you should ask the question whether you’re actually going to deliver more information more effectively by specifying than by not.

So that was product standards - what about process standards?

Process standards

A process standard doesn’t tell you what to produce, but it does tell you how to go about doing it.

Examples of documentation process standards are:

• Australian Standard AS4258 - Software user documentation process
• the pair of British Standards republished as Australian Standard AS4598

Another name for a process standard is a ‘methodology’: a set of procedures.

Let’s look first at the pair of British Standards. They were developed by an company called ICL (now part of Fujitsu) in the UK under contract from the British Standards Institution. Now this is unusual - most standards are developed by committees, and as a result are fairly unreadable. But these ones are actually well written.

There are two standards in the set, one dealing with paper documentation and the other with online documentation, but they both cover the same sort of ground: the use of audience and task analysis, and the process of planning and developing software documentation.

For those of you who have not yet come across it, I will briefly explain audience and task analysis. I’ll keep it brief because most technical writers use it already.

The idea is to start your documentation planning by deciding who the ‘audiences’ for the documentation are: who are the different groups of people who might need to use the product that you’re documenting?

Having decided that, you then figure out what each of those audiences is actually trying to achieve with the product - what tasks are they trying to perform?

From that you work out what information they need in order to perform those tasks, and then you map all of that information onto a table of contents that matches both the audiences and the tasks.

Sounds easy, right?

Anyway, suffice to say that AS4598 covers how to do this, and tells you how to document your analysis and decisions. It also gives some general guidance on good practice in English usage, page layout, typography and a few other useful things. But it doesn’t tell you what to put in your documents, or how to lay them out, or what headings to use.

The pair of British Standards (which were published only recently in this country) provide guidance - they’re like a textbook.

AS4258 is an Australian-developed standard which, by the way, should become an international ISO standard around the end of this year, and will be the first Australian software engineering standard to make that transition.

AS4258 is also a process standard, and it sets out pretty much the same sort of approach as the pair of British Standards. Why have both the British and the Australian standards published if they both do the same thing? Well, the difference between AS4258 and the others is that 4258 is not written like a textbook, it’s written like a specification.

It still tells you how to plan and develop user documentation, and it still doesn’t tell you what to put in your manuals, or how to lay them out. The intention is that people call AS4258 from a contract, and if the person responding to the contract doesn’t do what AS4258 says, they can be sued. The British standards aren’t suited for this purpose - they’re written to be readable and to inform. AS4258 is written to be read in a court of law.

That’s not to say that it’s completely unreadable (I was heavily involved in its development myself, so I hope it’s not too unreadable!), just that it’s intended for a different purpose.

So what’s the effect of these process standards?

Well, by instructing people how to use audience and task analysis, and by giving purchasers the tool to contractually oblige suppliers to use audience and task analysis, these documents will increase the amount of thought that people put into the design and content of documentation.

Does this mean more work for technical writers? Yes it does. It means that more effective documentation will be developed, and that people will be more likely to use, and therefore to demand, good documentation with their software.

Process standards (well, the ones that I’ve mentioned, at least) will improve the lot of the technical writer, rather than just forming a millstone around our necks.

Quality standards

Last, I’d like to deal with the third type of standards: quality standards.

Most people will have heard (at least) of the ISO9000 series of standards. These are quality standards, but there are others, including:

• the Therapeutic Goods Act Code of Good Manufacturing Practice (which is mandatory for companies manufacturing any health-related products)
• CMM and SPICE, which are quality standards (well, sort of) for the software industry

Quality standards don’t tell you what put into your product, or even what processes to use to make your product. Quality standards tell you how to make sure that the other standards that you use (process and product standards) are actually being adhered to.

Let’s take ISO9000 as an example. ISO9000 requires a number of things, including:

• document control, so that everyone’s working from up to date procedures
• internal audits to make sure everyone’s following procedures
• regular review of procedures to make sure they are up to date
• checks to make sure that your products meet whatever product standards you are using
• checks to make sure that you’re delivering what your customers actually ask for

Notice that quality standards don’t tell you which processes to use, or what product standards to use - they just ensure that you have the infrastructure in place to make sure that your product and process standards are actually effective.

ISO9000 works by having an external auditor come round and assess your organisation - you either pass (and get ‘certified to ISO9001’) or fail.

CMM (‘Capability and Maturity Model’, developed by the Software Engineering Institute at Carnegie Mellon University in the US) takes the ideas of ISO9000 and extends them; rather than a pass or fail, you get a number from 1 to 5:

• 1 means that you’re flying by the seat of your pants - you’re developing software but you don’t know how or why
• 2 means that you’re developing software reasonably reliably (not necessarily reliable software, though) - this generally means that you’re copying the best bits of the previous version and modifying it
• 3 means that you have standards and procedures in place (roughly equivalent to ISO9000 certification, although some people dispute this)
• 4 means that you have all of the above, plus a system of metrics
• 5 means that you have all of the above, and you’re doing full-tilt TQM quality improvement

SPICE takes the idea of CMM and extends it further - instead of giving a single number for your whole organisation, it gives a number for each process (testing, specification, etc).

What do these quality standards (ISO9000, CMM and SPICE) mean for technical communicators?

Well in order to get ISO9000 certification, or in order to move from one level of CMM or SPICE to another, what’s mainly involved is the writing and implementation of procedures.

Now there are three ways to write procedures:

• have the staff write them
• have an external quality consultant write them
• have a technical writer write them

The major problem with having the staff write them is that they tend not to get around to it. And the problem with having an external consultant write them is that they generally can’t write. So guess what the best answer is?

So to summarise: do documentation standards mean more work for technical writers? The answer is yes.

Is this ‘good’ work or ‘bad’ work? Well it depends on the kind of standard:

• product standards sometimes mean ‘bad’ work - worthless additions to the costs and time required to complete a project, for no gain; of course there are exceptions
• process standards and quality standards mean ‘good’ work; there are exceptions here too

Any questions?