What exactly is technical writing anyway? Do you need a technical author? This page tries to answer these and other questions. But first...

Why can’t our developers write our documentation?

This is a common question. The answer is - they can, if you appreciate the pitfalls.

Firstly, your developers will tend to take an internal view. They understand your product thoroughly and will consequently make assumptions about how much the user understands and even about what they want to know. These assumptions will almost certainly be wrong.

What is necessary is a process of perspective inversion - documentation should be written from the user’s viewpoint. Your users will start by knowing nothing about your product. Worse still, they may even be averse to it - ’Oh, it’s the new system and we’ve been told we have to use it’. In such an environment, confusion turns rapidly to reticence and reticence to resistance.

A technical author, coming to your product afresh but with motivation and astuteness, is ideally placed to produce documentation engineered for the user’s viewpoint.

Secondly - wouldn’t you rather have your highly-trained and skilled developers working on the next new product instead? Developers usually just hate doing documentation, too.

What exactly is technical writing?

Put simply, technical writing is the presentation of information on any scientific, engineering or technological topic in the form most suited to its user. A technical author can be involved in producing printed product guides but equally in a diverse range of other activities such as creating on-line help systems, writing and editing textbooks, preparing training courses, compiling service guides and parts manuals, designing and building intranets and their contents, ensuring that error messages in software are meaningful, assisting in designing software user interfaces - the list is almost endless.

Three guiding principles stand out - information should be:

• Appropriate to its audience
  
  
• Clear and precise
  
  
• Accessible

To achieve this, it is not enough merely to collect the required data and write a book, compile on-line help and so on. First we must analyse the information need and the intended audience for the information. We then apply a process of information design to find the format that makes the information most usable.

For that matter, what’s technical editing?

This is easier. We define technical editing as the improvement of any written technical material by the application of sound principles of technical writing.

How do we go about it?

The approach a technical author brings to your documentation tasks can be summarised as follows:

The sections below elaborate on these ideas.

We know what we are writing

This may sound silly but it is important.

Here is a simple example: in software application documentation, a good starting point is the model that divides the bulk of the printed documentation into ‘user’ and ‘reference’ guides. There may be a need for some or many other guides, depending on the complexity or versatility of the product. There may also be products for which this is not a good documentation model but it should always be considered.

User guides and reference guides serve different purposes. Readers look in user guides to be told how to do something, while they look in reference guides to be told what something is or does. Put another way, user guides describe actions - what someone can do with the product - and reference guides describe things - what the product is composed of.

By providing both types of documentation, we automatically cater both for users who want to know how to perform a specific action, procedure or process with the product, and those who want to find out what action a particular command, feature or dialog performs. When augmented with suitable indexes and maybe on-line help, the user then has a number of entry points into the documentation that cater for different viewpoints, states of knowledge and experience.

We know who we are writing it for

Technical authors first identify the likely audience for documentation. It may not be a single audience. Once we have identified who we think we are writing for, we are in a position to think through what they need to know, then design and write it.

For example, the writing style that is ideal for a user guide for a software application differs from that for a pre-sales management overview. Similarly, that for a service manual differs from a company procedure and so on.

We know how to organise the information

Once we have defined what is to be written and the relevant audiences for the information, we are in a position to carry out an outline design. This process applies equally to printed documentation and to documentation presented in any other delivery medium, such as on-line help, Web or hypertext pages and so on.

We apply a process of information design, analogous to any other form of engineering design, to find the format that makes the information most usable.

We know what we should include

At this stage we know what information is available. We have identified all our sources and resources, both human and printed, and we can begin a filtering process. In many cases this stage involves more a process of deciding what should not be included rather than what should.

A by-product of this stage is a set of dependencies that highlight risks, key sources, missing information and the means to find it. Ultimately, the quality of any documentation depends on the sources of information for it - poor sources, poor documentation.

We know how to use language

The English language is very rich and capable of amazing subtlety of expression.  Sadly none of this is any use to us when preparing technical documentation. Because we are striving always for clarity and precision, we adjust our use of English to the target audience, often using limited vocabulary, simple tenses, simplified grammatical structures and so on as appropriate.

This is of particular importance if documentation is to be used by people who do not have English as their first language, often the case if you sell into the export market.  For example, consider the following uses of tense:

‘The drivers will have been configured when the application was installed’

‘The installation process automatically configures the drivers’

The first example is more accurate, arguably better English, but far harder for a non-English reader to understand. Similarly, we avoid the passive voice, keep sentences short, use simple words in preference to complex ones, avoid slang and unnecessary and ambiguous words.

We know how to use terminology

Whole books have been written about the use of terminology and complex software systems designed to compile terminological databases so that meaning is not lost in translation. Despite all this, the basic rule we apply is very simple:

‘Call a spade a ‘spade’, do so consistently, and define it if necessary’

There is nothing more confusing for a new user of a complex product than having to cope with its parts or underlying concepts being called one thing in one part of the documentation and another thing in another. This is bad enough in English, but a moment’s thought will reveal what a nightmare it can become if translation into a foreign language is involved.

Sadly, this situation arises all too readily in practice.  When development teams work together on a new product, they are often grappling with new concepts, new features, new ways of using existing products and even new ways of designing software. This provides an environment in which it is all too easy for different parts of your team to call the same feature by different names.

The solution is to standardise terminology at an early stage. This is not too hard to do and can be thought of as a natural extension of processes such as standardising data dictionaries or the names of global resources. If a technical author is involved at an early stage of the development they can assist in, or be responsible for driving this process.

Contact Tel/Fax +44 1736 810000