1. 38 Writing
Saul Wurman (2001) stated that ‘All
projects start with a question, yet
few spend enough time crafting this
question.’ The ultimate success of any
project depends very much on the
initial questions asked — accurately
identifying the needs and finding ways
to meet those needs.
From a technical communicator’s
point of view, there are three basic
questions we need to ask:
1. What am I being asked to
communicate?
2. Who will be using it?
3. What is it for?
The answers to these three simple
questions should be the foundation on
which the documentation is based.
What is it?
The broad picture
Ideally the technical communicator
will be involved in the early stages of
a project, where the aim is to learn as
much as possible about it — not simply
what the product or process is but also
where it fits into the overall scheme of
things. The documentation is not a stan-
dalone item but an integral part of the
product. Hackos (1994) suggests several
questions that should be asked:
Why is the product being produced?
How will it be placed relative to the
competition?
Who is the competition?
What documentation do they provide?
The answers to these questions not only
provide a broad picture of the documen-
tation likely to be needed but also help
highlight any constraints (for example,
budget and time).
The ‘nitty gritty’
If we are coming to the product ‘cold’,
that is with no specialist knowledge,
how do we gather the information we
need to produce the documentation?
The information sources available, to
a certain extent, depend on the prod-
uct itself. The following paragraphs
describe some possible sources.
Libraries. These can be a source of
valuable background information on a
wide range of topics, from databases to
sonar. In addition, a library is a source
of indices to other libraries, repositories
of periodicals and journals and, most
importantly in the technical area, holders
of reference volumes and extracts
(university libraries, if local, are
particularly good sources of information
of this kind). The other main resource in
a library is the librarian, who is almost
invariably a fount of information on
the best places to find information on
specific topics.
Remember, too, that most large com-
panies keep a technical library.
Online Databases. Increasingly, mod-
ern reference material is held online in
a database of some kind. Often com-
panies are members of organisations
that give them access to specialised
databases relevant to the fields they
operate in, and many product suppli-
ers provide background information on
their websites.
Internal documents. From the start
of any project, an array of documents
is produced, including marketing
material and specifications. Marketing
material is usually a good place to
start, as its authors often have a clear
idea of what the product should do
even before it exists! All existing
documentation should be studied in
the drive to become an ‘expert’.
Peer resources. Possibly the most
valuable source of information is the
other people working on the project.
The problem with this is that the
information is, more often than not,
only in their heads and not down on
paper. The only way to get it is by
talking to the relevant people. Talking
to someone face-to-face is a complex
method of communication that is often
taken for granted because we do it every
day with little or no conscious thought.
A survey (Dillon, 1990) identified 16
areas where questioning technique is
important. These include journalism,
education and management but there
is no mention of technical communica-
tion. Interview techniques for technical
communicators tend to fall into a series
of pragmatic ‘dos and don’ts’. So what is
the best approach?
Initially it may be worth approaching
the engineers and asking them:
1. For a brief overview of the product;
if you have read the marketing
material, you will know roughly what
they are talking about and can fill in
gaps in your knowledge.
2. To suggest reference sources that
you can look up (for example, books
to buy or borrow).
This approach has two advantages:
you are showing that you appreciate
that they are busy and will not take up
too much of their time, plus you are
showing a willingness to learn. Once
you know more, you can arrange a
meeting to get some relevant questions
answered. Before any interview, you
should do two things:
1. Inform the interviewee why you
have asked for the meeting and
what you want to talk about. Not
only is this common courtesy but
it allows the interviewee to prepare
for the meeting so that it is more
productive.
2. Prepare the questions you are going
to ask. Ideally send them to the
interviewee in advance and stick
to them. If the meeting is managed
well and does not overrun, not only
will you obtain useful information
but you will leave the interviewee
more amenable to providing further
information if required.
Product. The product itself is the other
main source of information. Ideally,
you should have access to the product
from the early stages of the project.
The way in which the product is used to
gain information falls into three main
categories:
1. The methodical approach. This
means going through everything
in order (for example, every screen
in the software). It ensures you
see everything but you may not
get a feeling for how the product
accommodates the flow of user
tasks.
2. The task-based approach. This
starts with a list of tasks to be
accomplished with you as the user.
It gives a feel for the product from
the user’s perspective but, unless
you have covered every possible
task, you may miss some features.
The writing process: research
In the first of a series of four articles, Damien Braniff explores
the elements that make up the process of technical writing.
2. 39
3. The ‘jump in and swim’ approach.
This is most appropriate to software
products, where you start with
the first screen and see where the
buttons take you, following the
product’s navigation system.
Whatever approach you take (often a
mix of all three), you must record every-
thing as you go.
Who will use it?
This question is, or should be, at the
heart of any documentation. Technical
communication is all about transferring
information between groups of people.
If you do not know your audience, the
chance of producing documentation
that will be useful and meaningful to its
members is slim.
Hackos says that ‘audience analysis is
one of the most widely accepted parts
of the publications planning process
and one of the least effectively per-
formed’. It is acknowledged as being
important but time and resources are
rarely allocated to gather information
about the users of the documentation.
A poll on TECHWR L (a technical com-
munication e mail list) tends to confirm
this: less than 16% of respondents
said they always or frequently had any
contact with the eventual users of the
product (see www.raycomm.com/
techwhirl/polls/techwhirlpollresults.
php3?pollID=72). Over 68% said they
rarely or never had any contact with
users. Personally, in over 20 years of
working in both small and large com-
panies, I have only ever once had direct
contact with users.
Ideally, you need a profile of the ‘typi-
cal’ user, which, at its most basic level,
should include:
Educational level
Technical background
Native language
Degree of familiarity with the product
or with similar products
Reason for and frequency of use
The environment in which they work.
Gathering this information takes time
and money and is rarely budgeted for
(I have never worked anywhere that
carried out formal audience analysis),
even with the arguments that a better
understanding of the audience leads to
better documentation and a reduction
in documentation and support costs.
Where time and money are limited,
there are still some options available:
Use internal sources. Talk to anyone
in the company that has any direct
contact with the user — customer or
technical support, training and sales
can provide useful information.
Check with the marketing people.
Have they done any analysis of the
customer base?
Send a survey or questionnaire to
a random sample of users. This is
not to be done lightly. Traditionally,
response rates to surveys are very
low but a higher response may be
obtained if people in the sample feel
it is beneficial to them to provide
feedback. Ideally, a survey should be
carried out by a professional survey
company but this is expensive. If you
have to do it yourself, try to be as
professional as possible and follow
the guidelines offered by Fowler
(1984, 1995).
Telephone survey. This can be
effective and is the next best thing to
actually visiting the user but, again,
the design of the questions is crucial
to the success of the survey.
Site visits. These are ideal as you
meet users in person and can see
what they do.
Whatever methods you use, the amount
of information may be very limited,
but even this will allow you to begin to
get a feel for the ‘who’. Almost invari-
ably, the initial information you gather
will show that the audience is not
homogenous and is, at best, made up of
several homogenous groups — a typical
breakdown might be to divide them
into technical experts, those who are
competent, and novices. Reading is an
active process and readers will interact
with the documentation in different
ways, making their own assumptions
about it and having their own expecta-
tions based on previous experience.
Anything you learn about the audience
has an immediate impact on the type of
documentation that you produce.
What is it for?
As well as understanding the users, you
must understand the tasks they need
to perform and reflect those tasks in
the documentation. Depending on the
product, task analysis can be much
more complex than audience analysis.
It not only involves determining what
tasks the users perform but also how
they will interact with the product. At
the start of the project, a list of high-
level tasks will give the documentation
structure but this is only the beginning;
you may need to go down several levels
to complete the analysis. At a high level,
initial tasks may be defined as:
Installation
Configuration and customisation
Diagnostics and troubleshooting
Maintenance
Operation
Disposal or recycling.
From the list of high-level tasks come
the individual tasks to be performed in
each category. As in audience analysis,
the best way to collect information is
directly from the people who will carry
out the tasks. You may use surveys,
interviews and observation (watching
users perform tasks) to achieve this.
At this stage, you also determine
where the tasks will be performed. This
often forgotten question can have a
profound effect on how information is
presented. For example, a manual or
user guide on normal paper may not
be suitable if it is to be used in areas of
high humidity; laminated material may
be more appropriate.
The next stage
When you have done all this, you will
know all about the product, what it is
for, who will use it and what tasks they
will perform. Now all you have to do is
write the documentation! C
References
Dillon, J T (1990) The Practice of
Questioning. Routeledge.
Fowler, F J (1984) Survey Research
Methods, Applied Social Research
Method Series Volume 1, Sage
Publications.
Fowler, F J (1995) Survey Research
Methods, Improving Survey
Questionnaires: Design and Evaluation,
Applied Social Research Method Series
Volume 1, Sage Publications.
Hackos, JoAnn T (1994) Managing Your
Documentation Projects, NY, John Wiley
and Sons, Inc.
Wurman, Saul (2001) Information
Anxiety 2. Que.
Damien Braniff MA FISTC LCGI MIQA
is a technical writer with more than
20 years’ experience, spanning both
hardware and software.
E-mail: jd_braniff@yahoo.co.uk
3. 35Writing
Introduction
In this article, we will be looking at plan-
ning in the project management sense,
rather than planning the content of a
document. The latter, planning how to
present the information that you gather
to the user, will be covered in the next
article in this series, on the ‘writing’
stage.
Planning any project, documentation
or otherwise, involves:
Capturing therequirements and, from
them, defining the scope.
From the scope, working out the types
of resource and how much of each is
required.
Deciding how the project will be
managed and controlled.
There is also a broader aspect to plan-
ning, called strategic planning, which
looks into the future to determine the
direction that an organisation needs to
take to meet changing requirements and
prosper in the future. This applies to us
as individuals as well, influencing how
we plan our careers and develop our
skills.
Project planning
The level of involvement that the writer
has at the planning stage can vary
greatly — anywhere from 0-100%!
In a large organisation, there will
probably be a project manager with
responsibility for this activity and
usually ‘all’ the writer has to do is
provide time estimates, meet the dead-
lines and follow the standard templates.
If you work for a small company,
perhaps as the sole writer, then you will
probably be more intimately involved in
the planning process.
Planning, no matter how informal it
may be, is crucial to the success of any
project. Hackos (1994) says that good
planning and management is needed to
keep ‘projects under control and profit-
able’. Project management is a huge
subject, with books written on every
aspect of it, but here we consider only
two:
1. Scope — what the project will cover
2. Schedule — when the project will be
delivered.
Scope
The scope basically defines how big and
complex the project is and exactly what
it covers. This is, to a large extent, deter-
mined by the research done in the first
stage of the writing process and also by
what the customer wants.
As part of the research phase, you
carried out a task and user analysis so
you should know roughly what type and
level of documentation is needed. For
example, there might be an Installation
Manual, System Administration Manual,
Quick Reference Guide and User Guide.
If you’re anything like me, you will also
have started, mentally at least, to sort
the information you have gathered into
the various documents needed. You
may even have gone so far as to create
outline manuals with chapter headings
and a brief synopsis of what each will
contain.
All this gives you a feeling for how
‘difficult’ each document will be
to produce and how much work is
involved. It also allows you to create
a ballpark figure for the size of each
document and to produce a rough esti-
mate of the number of pages that need
to be produced.
Schedule
This is a bit of the process with which
the writer often has too little involve-
ment. In many places I’ve worked,
scheduling has ranged from ‘we need it
by…’ to ‘do you think three weeks will
be enough for this…?’ Oh, and by the
way we need everything delivered at the
same time!
To create a workable schedule, you
first of all need to know how long it will
take to produce the documents. Van
Laan and Julian (2001) state that the
time to create any given document can
be calculated using the formula shown
in Figure 1.
If you’ve got your estimates fairly
close (that comes with experience),
you’ll have a good idea of how long the
project will take (always err on the safe
side). As a general rule of thumb, for
creating new documents through first
draft to final version, Van Laan and
Julian suggest:
Ten hours per page for highest quality
documentation
Seven hours per page for documents
people ‘need and use’
Three to six hours per page for
minimally usable documentation.
Now you have estimated the time it will
take to produce the documents, you can
create your schedule. This can go one of
two ways:
1. Fantasy land
You know the amount of time
needed, you know the resources
available, you allocate the resources
accordingly, you say when the
The writing process: planning
In the second of a series of four articles, Damien Braniff
looks at the planning stage of the writing process.
Figure 1. Formula for calculating time required to create a document
Time = Size x Scope x Quality
where:
Size = estimated page count
Scope = complexity:
1 = fairly straightforward; familiar product; developers available
1.5 = more complicated product; learning curve; one review cycle
2 = complicated product; no specifications; more than one review cycle
2.5 = new product; changes ongoing; multiple reviews needed
Quality = what is acceptable:
2 = information must be complete
2.5 = as 2 plus more than bare minimum; proofed; style guide
3 = as 2.5 plus indexed; edited; additional information added
3.5 = as 3 plus illustrations and graphics; structured; task-based
4 = as 3.5 plus layout designed for maximum usability and tested
4. 36 Writing
documentation will be ready and
everyone says, ‘Fine’. (I’ve never
actually seen this happen but maybe
I’ve just been unlucky!)
2. Real life
You know the amount of time,
you know your resources and you
know when the documentation is
needed. You then work out what you
can deliver by the deadline, given
the resources you have, and then
compromise where you can.
You can compromise by:
Pushing for additional resources to
get everything done by the deadline
Prioritising the documentation and
offering the ‘main’ documents by the
release date, with the others to follow
Agreeing to release draft documents
Scaling down the scope of the initial
release
Moving the deadline.
The number of options available will
vary from project to project but,
almost inevitably, some compromises
are needed. If the technical writers are
involved in the early stages of a project
then, assuming their estimates are
taken into account when scheduling the
project as a whole, compromises can be
kept to a minimum.
Document plans
When the schedule for the documenta-
tion has been agreed (including any
compromises), then you can start to
formalise it by creating a document
plan for each manual. This is to ensure
that there is no confusion about what is
to be produced, with each plan speci-
fying what the document is, the content,
the delivery date, who will produce it
and any milestones along the way (first
draft, final edit and so on). A document
plan for a product will, ideally, consist
of the following sections:
1. Title page: identifies the product
and the current version number of
the plan.
2. Overview: details what the plan
is for (producing documents for
project X) and who it is aimed at
(management, customer and so on).
It should specify the scope of the
documentation and any assumptions
made or constraints to be met.
3. User profile: identifies who the user
is for each document. Remember
that not all documents will have the
same readers.
4. Existing documentation: identifies
any existing documentation for
the product. This may be existing
manuals that are to be updated or
specifications if it is a new product.
5. Documentation needs: identifies
what documentation is required, for
example manuals or online help.
6. Publication plan: this is essentially
a list of the documentation needed
as determined by the user and task
analysis in the research stage.
7. Process and schedule: identifies
the milestones, review process and
approval or sign-off procedures.
8. Resources: identifies the technical
writers, designers and graphic
artists available. It also includes
any other groups that need to be
involved, such as quality assurance
or testing, and any tools required.
9. Issues: any issues that may affect
delivery should be raised, such as
insufficient resources to meet the
deadlines.
Budget control
A vital part of the planning process is
getting the budget right — the aim is
not only to produce excellent documen-
tation on schedule but also to make
money!
Costing
Excluding printing, the main cost
factors that need to be considered are:
1. Direct labour costs such as writers,
CAD engineers, illustrators, technical
clerks and administration staff
2. Materials such as paper and CDs
3. Office overheads such as PCs,
software and other equipment that
might be bought or hired
4. Indirect labour costs such as
holidays and sick leave.
Documentation is labour-intensive and
by far the major cost is the manpower.
To calculate the cost of the project,
you can create an ‘estimating table’ in
a spreadsheet package like Microsoft
Excel. Down the left-hand side of the
table, list each document and the
chapters in it. Across the top of the
table, list everyone who may be involved
— writers, illustrators, administration
staff, managers and so on. Then fill in
the number of hours for each person,
add these up and multiply by the appro-
priate hourly rate.
Of course, the basic hourly rate is not
the true cost to the company. Taking
into account all the overheads, Hackos
estimates that the actual cost for most
US companies is 2.5–3 times the rate
paid to their employees.
Generally speaking, the cost to the
customer is the sum of the costs listed
above, plus a profit margin and VAT (if
applicable).
Control
Once you’ve worked out the budget and
started the job, the aim is to ensure that
you stick to it — if you don’t, then there
may not be any profit!
To keep control, the project must be
regularly monitored and supervised
to ensure that those working on it are
operating within the specified cost and
time constraints. Any deviation must
be dealt with as soon as possible and
the project steered back on course.
There will usually be some slippage
(and you should have allowed some
leeway in the estimates) but time lost in
some areas may be made up in others.
If the slippage is due to the customer
(for example, changes to the specifica-
tion), it is legitimate to charge for the
changes, as they were not what the
original estimate was based on. If the
slippage is due to internal factors, these
should be noted and built into any
future estimates.
Strategic planning
While it might be said that strategic
planning is not, at least directly, a part
of the writing process, it is integral
to the providing customers with what
they need and, indeed, to the continued
employment of technical writers. We
have all heard the saying, ‘anyone can
write’ and, too often, this is taken to be
true; the documentation is produced by
whoever happens to be free when it’s
needed.
When we think of strategic planning,
we tend to think of large companies
planning for the future but it’s not just
If the technical writers are involved in the early
stages of a project then, assuming their estimates
are taken into account when scheduling the project
as a whole, compromises can be kept to a minimum.
5. 37
for large companies. It is equally impor-
tant for everyone, right down to sole
proprietors. Some stages apply to all
organisations, whatever their size:
1. Know the marketplace.
Who is using technical writers
and in which industries?
What are the others doing?
Outsourcing? Using non-writers?
Do they know technical writers
exist?
What do customers want and are
we supplying it?
What are our competitors doing?
2. Identify trends: what is going to
affect technical writing over the next
five years? Factors may be:
Economic, such as outsourc-
ing to cheaper workplaces and
replacing hard copy with online
information.
Environmental, perhaps making
paper a ‘minority’ medium.
Political, perhaps regulations
(from the European Union, for
example) will require more or
better documentation.
Technological, perhaps products
becoming so user-friendly that
less documentation is needed.
3. Communication: talk to the
customers — we are, after all,
professional communicators. Are
they happy with what we do?
Does our documentation enhance
the product? Ideally, we need to
communicate at two levels:
With the ‘real’ customers — the
people who will use our docu-
mentation — so that we provide
what they need and want.
With the ‘paymaster’ — the per-
son who places the orders. If you
are lucky, this may be a customer
but, especially in larger organisa-
tions, this is often not the case.
In some ways, this is the most
important point because we deal with
people and it is often our interactions
with them that make or break a good
working relationship. I remember a
talk at Conference that described a
large contract which was awarded not
on price or quality (obviously impor-
tant and taken into consideration)
but on the fact that the customer felt
that they could ‘do business with’ the
supplier.
4. Determine what is needed to survive
and flourish:
How much will it cost and can we
do it cheaper?
If the cost is acceptable, can we
provide added value through bet-
ter quality?
Which competitors are doing well
and what are they providing that
we don’t?
All of this takes time and we must be
prepared to spend the time doing it. If
we do it well, it could give us an impor-
tant competitive edge and even keep
us working when times get tough. If
we know where the market, and clients
or potential clients, are going, we can
prepare ourselves to go with them. So
where might this lead us? Perhaps to:
Learn new skills (programming skills
seem useful at the moment)
Enter a niche market with little
competition
Try other types of writing, such as
marketing, science or journalism
Branch out into related areas, such as
testing or web design.
I could go on but the options will
be different for every company and
individual. One thing is sure: in an ever-
changing workplace, these are issues
that we all need to consider.
The next stage
In the next article, we’ll look at the
‘writing’ stage of the process. This will
cover how the information gathered is
presented to the user. C
References
Hackos, J T (1994) Managing Your
Documentation Projects. Wiley.
Society for Technical Communication (1997)
Technical Communication, Volume 44
Number 4 (strategic planning special issue),
STC Publications.
Van Laan, K and Julian, C (2001) The
Complete Idiot’s Guide to Technical Writing.
Alpha Books.
Damien Braniff MA FISTC LCGI MIQA
is a technical writer with more than
20 years’ experience, spanning both
hardware and software.
E-mail: jd_braniff@yahoo.co.uk
6. 40 Writing
Introduction
Having gathered the necessary infor-
mation, planned our approach and
prepared to start writing, we will now
look at how to deliver the information
we have gathered to the user — not at
producing the actual words (after all,
everyone can write, can’t they?).
Just as what is delivered is a product
of the user analysis, how it is delivered
should also be determined by what we
know about the user and the tasks to be
performed. Data on its own is, for the
most part, of little use to the user. To be
of use the information must be sorted,
filtered and structured in a way that is
meaningful to the user.
Shedroff proposes the Unified Field
Theory of Design (in Jacobsen, 1999),
stating that learning is a process where
we move from:
data information knowledge wisdom
Our aim is to get users to the ‘informa-
tion’ stage — knowledge (and hopefully
wisdom) comes with use of the product
— but how do we get them there?
Carliner (2000) suggests a three-level
approach:
1. The Physical Level: the ability to find
the required information.
2. The Cognitive Level: the ability to
understand the information found.
3. The Affective (emotional) Level: the
ability to be ‘comfortable’ with the
information and want to read it.
These seem well suited to technical
writing, perhaps because Carliner had
documentation in mind.
The physical level
This is the level that is most familiar to
technical authors, covering:
Page/screen design
Retrievability
Media selections
Production
Page/screen design
This is probably the first thing users
notice about any documentation — what
it look likes. If initial impressions aren’t
favourable, the likelihood that it will be
read closely is reduced.
The first thing to consider is page size
as everything else is constrained by this
choice — the font selection, positioning
of text and graphics, and the clarity of
illustrations. Several factors must be
considered when choosing page size:
Where will the manual be used and
stored?
User expectations — does the user
expect a particular size (possibly a
‘standard’ size for the industry or
what competitors produce)?
Costs — all documentation costs
money and there may well be
constraints involved.
Size and quality of illustrations
provided.
With the page size chosen, the writer
still has several decisions to make:
What format to use? Single or double
column?
What font to use? Will it be easy to
read? Will it appeal to readers?
Technical writers are not graphic
designers or layout specialists, nor are
they typographers — they do not need
to be but they do need to understand
the basics. Williams (1994) lists four
basic principles to page design:
1. Contrast: making different stylistic
elements visibly different; for
example, using serif for body text
and sans serif for headings, rather
than two very similar serif faces.
2. Repetition life: repeating visual
elements (such as spacing and
heading weights) throughout the
document to develop organisation
and promote the image of the
document as a single cohesive unit.
3. Alignment: avoiding placing
elements arbitrarily on the page.
Every element should have some
visual connection with another
element on the page.
4. Proximity: using space to group
related content and distinguish
unrelated content.
Williams points out that these are
principles, not rules and, once you’ve
mastered them, breaking them is
acceptable in certain circumstances. He
also lists three types of relationship that
can exist between fonts:
1. Concordant: using one font family
with little variety in style, weight and
so on. This gives a harmonious, even
sedate, look to the page.
2. Contrasting: using fonts that are
clearly distinct from each other.
3. Conflicting: using fonts that are
similar in style, weight and so on
creates conflict. They are neither
the same (concordant) nor different
(contrasting) so they conflict.
Today it is common to ‘mix and match’
fonts and research in legibility (Tinker,
1963; Spenser, 1968) provides sound
guidelines as to which combinations
make text visible, easy to read, and least
tiring on the eye.
Retrievability
This is about helping users find what
they’re looking for. It is the technical
writer’s ‘bread and butter’ and involves
providing suitable navigational aids (for
example, tables of contents, indexes,
running headers and footers). There is
nothing new in this but it must be done
well — good design may not be noticed
but bad design stands out, and can
adversely affect the user’s opinion of
the documentation and, ultimately, of
the product.
Media selections
This is about how the documentation
is delivered, which is usually printed or
online, and might, for example, include
audio recordings. As with everything
else, media selection should be influ-
enced by the user and task analysis
— what do the users need and want?
Too often, media are selected with cost
(and other similar factors), not the user,
in mind. My experience of users is that
most of them still prefer printed docu-
ments and there is anecdotal evidence
that providing a good, usable manual can
be a major selling point for a product.
Even producing a much reduced set of
documentation (for example, a basic
user guide) in print, with the bulk of the
The writing process: writing
In the third of four articles, Damien Braniff examines
the information design stage of the writing process.
7. 41
documentation online, could be a big
plus with the customer.
Give the customers what they want
because, if you don’t, the chances are
somebody else will (unless you operate
in a niche market).
Media needs to be selected early in
the process, as it can have a major
impact on the overall design — the
layout, typography and navigation.
Production
This is a relatively new area for the
technical author. When I began writing,
authors had no real involvement with
the production side of the process
— they produced ‘content’ (which was
input by typists), illustrators produced
graphics and so on. Now, however, the
author is often involved throughout the
process, from generating the material
to preparing masters and going to print.
With the advent of digital printing, this
may be simply a question of generating
a ‘press-ready’ PDF file. However, there
is enough traditional printing still done
to make it worth knowing the basics
(Wakeford, 1985).
The cognitive level
The cognitive approach to design
focuses on defining users’ perform-
ance goals and preparing a solution
to meet those goals. For the technical
author this is about providing the ‘right’
content and, again, should be driven by
the user and task analyses carried out.
Users want information on specific
topics and the physical design has
brought the user to the information, but
is it the right information? There is a
temptation at times to simply spew out
all the information there is on a given
topic and hope the users find what they
need. However, if the user/task analyses
have been done properly then you
should not only know what informa-
tion is required but also who wants the
information and the different reasons
why they might want it. Knowledge of
the user allows the information to be
provided in a suitable format with an
appropriate level of ‘pre-processing’
applied to the information before it
reaches the user. For example, if you
are writing for both novice and expert
users, information can layered to cater
for both types of user in the same docu-
ment.
When providing information, the main
aim is to match the information to both
the user and the task at hand.
The affective level
This last level is probably the most
removed from traditional technical
writing and much more biased towards
traditional information design where a
major part of the task was to persuade
the user to use the product. It is all
about motivating users, in our case, to
use the documentation! Carliner defines
the following elements of affective
design:
Attention. The user must want to
read the information. If it doesn’t get
read then, no matter how good it is, it
is ultimately useless.
Motivation. If the user finds the
information and it’s relevant, the
motivation should be there to use it
again. Whatever the information (‘how
to’, ‘nice to know’ and so on) it must
be relevant to those reading it.
Change Management. Products can
have quite a substantial effect on
how things are done and users are
often wary of change. People are often
sceptical about new technology and
we need, where possible, to ease that
scepticism/apprehension — how did
we view computers when first asked
to use them?
Language. Language is a powerful
tool; the words we use to convey a
message can be almost as important
as the message itself. By using basic
rhetorical techniques (emphasising
benefits, addressing concerns and
so on), we can persuade the user
to read the document and, by
pitching it at the right level for the
intended audience, we can make it
understandable and usable.
Cross-cultural Communication.
Cultural differences are not simply
between cultures and languages.
There is a whole range of cultures
and sub-cultures within every society
and these also need to be considered
(possibly as part of the audience
analysis).
Social and Political Impact. Even
the simplest of messages can have a
variety of social/political implications
and we need to be aware of this.
‘Political Correctness’ — need I say
more?
Legal and Ethical Issues. This is one
area that affects most writers as it
covers such areas as copyright and
privacy. It also raises the matter of
personal ethics — can I write for
such a company, document such a
product?
Client Service. Most literature on
document design emphasises that the
user is king, yet most writers often
don’t write for the user — they write
for whoever pays the bills; it is them
that we need to satisfy — meeting the
users’ needs is often a bonus!
Summary
Carliner’s model implies a move away
from providing the user with informa-
tion to solving problems for the user.
Simply providing the information
isn’t enough — it’s of no use at all in
a manual nobody reads. The methods
used come from various sources,
including graphic design and instruc-
tional design, but can be summarised
as:
Attractive layout. If it looks
‘professional’ then it’s more likely to
be read.
Navigation. If it is read, then the user
has to be able to find the required
information quickly and easily.
Accurate. Once the information has
been found it must be accurate.
Well written. Not only must
information be accurate and easy to
find, it must also usable — users must
be able to understand it when they
find it.
In the next article, we’ll look at the
‘evaluate’ stage of the process. This will
cover how the project went and how it
could be improbed. C
References
Carliner, S (2000) ‘Physical, Cognitive,
and Affective: A Three-part Framework
for Information Design’, Technical
Communication (Third Quarter), STC
Publications.
Jacobson, R (editor) (1999) Information
Design. MIT Press.
Spenser, H (1968) The Visible Word,
London. Lund Humphries and Royal
College of Art.
Tinker, M A (1963) The Legibility of Print.
Iowa State University Press.
Wakeford, J (1985) ‘Printing Simply
Explained’, in R Dodd (ed) The ISTC
Handbook of Technical Writing and
Publication Techniques, ISTC.
Williams, R (1994) The Non-Designer’s
Design Book. Peachpit Press.
Damien Braniff MA FISTC LCGI MIQA
is a technical writer with more than
20 years’ experience, spanning both
hardware and software documentation.
E-mail: jd_braniff@yahoo.co.uk
8. 36 Writing
Introduction
In the course of this series of articles,
we’ve looked at how to gather the
information we need, plan our
approach, produce our documentation
and hand it over to the client. So, what
happens next?
Too often, we pat ourselves on the
backs — another project done and
dusted — and move on to the next
job. In doing so, we ignore or, at the
very least, pay scant attention to the
final stage of the writing process: the
evaluation stage.
Do we talk to others involved to
see how it went? Do we actively seek
feedback from our customers? Do we
check how well the figures proposed
for timescales, budgets and so on
match the actual figures achieved?
Unless the project went disastrously
wrong, the answer to these question
is often a resounding ‘No’. So, what
should we be doing?
We need to evaluate each project,
large or small, to see how the writing
process, and hence the documentation,
can be improved. Benefits to be gained
from such an evaluation include:
1. Seeing what worked well or not so
well, and incorporating any changes
into the next project.
2. Demonstrating to our customers
that we are continually trying to
improve the service we provide.
3. If the project hasn’t gone well,
showing our customers what went
wrong, plus what we intend do
about it, and so tempting them to
use our services again.
4. Improving estimates we produce
for later projects, and so increasing
our chances of getting the job and
making a profit!
Evaluation
In the 70s and 80s, efforts were made
to define clear measures of quality and
value that could define the success of a
project (Bandes, 1986). However, many
people thought that evaluation was so
complex and involved so many variables
that it was impossible for it to produce
relevant results.
This view has changed over the years
and now two basic evaluations can be
carried out:
1. User satisfaction
Does the documentation work?
2. Client satisfaction
This looks at the relationship
with the customer and raises the
question, ‘Is the customer happy?’
The first point is all about usability
testing, proving the documentation. It
should be noted that usability testing
is situational, and so the answers that
it provides may change as the product
develops. For example, early tests may
yield different results from those carried
out during beta testing of the product.
For this reason, it must be an ongoing
process.
The second point is probably more
important in a commercial context, as
it tries to measure benefits to the client
(the person or organisation that pays for
the work). These may include increased
revenue and reduced costs (Redish &
Ramey, 1995). Carliner (1997) suggests
that the clearest indicator of client
satisfaction is the client’s willingness to
provide repeat work or recommend a
supplier to others, which is what we are
all aiming for!
Project Review
Hackos (1994) suggests that four
distinct aspects of a project can be
evaluated:
Publications project: how the project
was run
Publications process: how usability
and customer satisfaction were
ensured.
Publications team: how the writers
and editors performed
Project’s future: how the project
catered for updates.
Publications project
This is essentially looking at how the
project was run — was it well planned
and executed? Project planning is a
huge area that I cannot explore in an
article of this type but there are some
factors that we can look at, irrespective
of the size of the project:
Were all the agreed milestones met?
Did the final documentation meet the
initial specifications?
Were the estimated schedules right?
Was the same team retained for the
whole project?
Was any usability testing performed?
Was sufficient time left for
translation and other localisation
activities?
If the answer to any of these was ‘No’,
we must ask ‘Why?’
From the answers, we can compile
a picture of what worked and what
didn’t work on the project. We can
then use that information to improve
our performance on our next project.
For example, it may have taken longer
than estimated for the client to check
the translation; we can allow for this
in similar future situations. Tabulating
estimated and actual values for timings
and costs provides a concise overview
of how the project went.
Publications process
This considers the quality of the
documentation and evaluates how well
the documentation works. There are
several ways in which this can be done,
for example:
Conducting surveys, by post or
telephone, to get feedback from real
users.
Monitoring the number of calls
received by sales, customer service
and technical support staff.
The writing process: evaluation
In the last of his series of articles, Damien Braniff looks at the
final stage of the writing process — evaluating what you’ve written.
Do we talk to others involved to see how it went?
Do we actively seek feedback from our customers?
Do we check how well the figures proposed for
timescales, budgets and so on matched the actual
figures achieved?
9. 37
The feedback received will give an
indication of how good or bad the
documentation is. Negative feedback
may indicate that the documentation
needs to be updated, in which case
we must decide on the severity of the
problem — must it be corrected now
or can it wait until the next release?
Whatever the problem may be, it is the
cause that must be determined. Was it
due to:
Late changes in the product?
Poor communication within the
project team?
Poor audience or task analysis?
Once we know the cause, we can factor
it into the next project so that the same
problem is less likely to happen again.
Publications team
This is about how the team (irrespective
of its size) worked together and how
its members fitted into the project as a
whole. The evaluation should address
questions such as:
Did the writers work well together
and support each other when
needed?
Were all the writers productive? This
is not a just a matter of comparing
the number of pages produced each
day but also takes into account what
each writer is doing, the material
available to each writer and so on.
Did the writers all get on well with
the engineers, programmers and
other contacts?
Note: While the time taken to write
a page may provide a rough guide to
productivity, the amount of time spent
on editing is often a better guide.
In some cases, especially if the
project went badly, evaluating the
publication team can be seen as a way
of allocating blame. However, it should
be promoted as a way to improve the
overall quality of the documentation.
Project teams that gel tend to
meet their deadlines and quality
commitments.
It is not only the writers that need to
be evaluated. The performance of the
manager(s) must also be examined:
Was the project well managed,
with all required resources made
available?
Were the writers protected, with the
manager acting as a buffer between
departments when required?
Was a good team spirit engendered
among the writers?
Answers to such questions provide an
overview of the team dynamic, showing
where its members worked well together
and highlighting any problems that may
have arisen. Again, this can be taken into
account when forming a team for later
projects.
Project’s future
When a project is completed and the
documentation handed over, it is very
rarely the end of the matter. Almost
invariably, there will be a series of
updates and enhancements. New
features will probably be added and
there may be several incarnations of
the product before it is eventually
withdrawn. How smoothly this
maintenance phase progresses is
determined by how well the original
project was run.
It’s important to make time at the
end of the project to complete the
administration activities that will
enable others to support the product
and to use the documentation as the
basis for future products.
Client satisfaction
The project review should cover user
satisfaction but client satisfaction is much
harder to evaluate because it depends
largely on what the client expects. It may
be that the client sees the documentation
merely as an adjunct to the product and
is content with it being present, looking
okay and having no factual errors.
As technical communicators, our goal
should be (to quote one quality guru)
not to satisfy clients but to delight
them. The best way to do that is to give
them value for money by showing a
good return on their investment. This
requires us to provide:
Increased benefits (for example,
additional sales or increased
productivity)
Reduced costs (for example, fewer
calls to technical support or lower
training costs).
These are measurable benefits. The
higher the savings we can generate, the
better the documentation will be from a
client’s perspective.
We can also take into account:
The amount of positive feedback
we receive from the client on the
documentation
How important the documentation is
in the customer’s decision to buy the
product.
Summary
Evaluation is an essential part of the
writing process that is all too often
relegated to a minor role as we rush on
to new and better things. This must not
happen — it’s too important for that,
whether we are working for a large
company or as a sole trader. We need
to evaluate to improve and to provide
the added value that, in the long run,
will bring us more work. C
References
Bandes, H (1986) ‘Defining and
Controlling Documentation Quality’,
Technical Communication (33:6-9), STC
Publications.
Carliner, S (1997) ‘Demonstrating
Effectiveness and Value: a Process for
Evaluating Technical Communication
Products and Services’, Technical
Communication (42:26-39), STC
Publications.
Hackos, J T (1994) Managing Your
Documentation Projects. Wiley.
Redish, J & Ramey J (1995)
‘Adding Value as a Professional
Technical Communicator’, Technical
Communication (44:252-265), STC
Publications.
Damien Braniff MA FISTC LCGI MIQA
is a technical writer with more than
20 years’ experience, spanning both
hardware and software documentation.
E-mail: jd_braniff@yahoo.co.uk
Negative feedback may indicate that the
documentation needs to be updated, in which case
we must decide on the severity of the problem –
must it be corrected now or can it wait until the next
release?
