Reference: technical writing terms

This section explains terms and concepts that are used on other pages of this website:

  1. Audience analysis
  2. Document design
  3. Documentation plan
  4. Project plan
  5. Task analysis

Audience analysis

Together with the technical writer, analyse the audience for the documentation and explore the factors that will make the documentation most usable for them. Contact users of your existing products and services, or identify people who are typical of your intended market and find out what they really need. Do not rely on your own guesses. Studying the audience gives you:

Start by determining:

Typical ways of researching the audience include:

Audience analysis includes the environment in which people use documentation. For example, if a roadside traffic engineer needs to put a manual on the floor and it is raining at dusk, a laminated document that uses a large text size would be beneficial.

Document design

Once you and the technical writer know who will read a document and what they need from it, you are ready to start thinking about the document itself. Before going into detail, think about the general level at which to pitch the information. Documents can:

For one-off tasks such as installation, a single sheet may be adequate. Find out what the audience needs to know about installation and show it concisely without unnecessary background information that they will not read. Installation instructions will often be discarded so do not put information there for future reference. There's no need for high production values on a single-use document: consider using any money saved on paper and printing to fund a good illustration of the connections, as commonly provided with computers. Illustrations can convey information clearly and can reduce translation costs.

When revising existing documentation, take the opportunity to consider whether the organisation, division into volumes, media or quality should change. Staying with a format may not serve the readers well and may not be the cheapest option: particularly for extensive documentation with large circulations, changes can be self-financing.

You may be able to reduce document size in various ways:

If you need to make existing printed documents smaller (whether to reduce costs, preserve quality or make them less daunting for their users), start by:

Documentation plan

The content of the documentation needs to be specified. If this is not done as part of the initial requirements definition, it should be done soon afterwards. Typically, your technical writer will do this (with much input from you). It is certainly something to consider as early as possible in the planning process. Examples of documents you might need are printed books, online help, classroom training notes, computer-based training courses and quick-reference aids.

For each document, the plan should explain:

The more complete and accurate the information at this stage, the greater the likelihood that documents will achieve their objectives and be delivered on time, on budget and in scope. When a technical writer asks you for input, be specific: for example, the audience isn't just 'users' but users of a particular type and with particular needs. You could define this by level of experience (novice or expert) or by job role (accounts staff or warehouse staff).

Project plan

A project plan should contain:

Additionally, the project plan may need to include external activities and costs, such as artwork design, photography, translation and localisation.

Freelance technical writers with experience of similar projects are likely to have a good idea how much they can produce in a given time.

Think carefully about the quality level that you need the writer to achieve. Sometimes, a low-level of quality is acceptable for a particular purpose but generally, you will be aiming higher than that. However, there may be no benefit in spending very large amounts to achieve top quality when a middle level would suffice. The perceived value of your product, the risks associated with misuse and the expectations of your customers all influence the approach you take to documentation. If you define an appropriate scope for your budget, it should be possible to produce effective documents even if you forego comprehensiveness and cosmetic enhancements.

Consider risks when you estimate resources. Your staff may lack experience or become ill. New systems or processes may not work as well as expected.

Various factors affect documentation projects:

Expect to adjust estimates as a project progresses. Even if you have retained a writer on a fixed-price basis, you need to know whether milestones are likely to be missed. If you are working on a time and materials basis, you also need to know whether the predicted cost is likely to increase. Bear in mind that doubling the number of people working on any project does not halve the time required. It is possible that additional time will be needed for co-ordinating their work and checking the consistency of the result.

Task analysis

Task analysis is the process of determining what the users of the documentation need to do. Task analysis may take the form of a task inventory, which needs to be detailed enough to enable the technical writer to judge the type of publications needed and their scope. At the broadest level, this will lead to categories such as:

These categories will then be subdivided until you have a scope and structure for each of the documents required. It may be that different types of users perform different sets of tasks, perhaps to different degrees of complexity. You will then need to consider whether you want to produce a single large document that users have to navigate and interpret for themselves, a set of smaller documents designed to support specific roles, or a modular information architecture from which a variety of documents can be assembled.

Sponsored by TechScribe technical writing