[ASC-media] Language technologies and software manuals
Tom.McGinness at csiro.au
Tom.McGinness at csiro.au
Thu Feb 6 10:27:50 EST 2003
THE MANUAL ALMOST WRITES ITSELF!
If all else fails...read the manual. But manuals are often so complex that
they confuse more people than they help according to Dr Cécile Paris of
"One reason confusion may occur is that manuals are often written some time
after the product, whether it is a machine, a tool or a piece of software,
has been finished," she adds.
But help is at hand. CSIRO researchers are improving the way manuals are
produced by developing tools to allow them to be created at the same time as
the software or product they refer to.
Traditionally, when writing a manual, a writer has to work out how to
achieve tasks using the product, then list the steps involved in clear,
unambiguous language. The process of documentation is separate from that of
If, on the other hand, the manual is created as part of an integrated
development process the manual and the product it supports will be entirely
consistent with each other. The content of the manual will be based on the
actual functionality of the product.
CSIRO has been working with the US Office of Naval Research (ONR) to make
this idea a reality.
"The ONR deals with massive amounts of documentation on a huge number of
incredibly complex hardware and software systems," says Dr Paris.
"This means that just making sure manuals keep up with specification and
functionality changes is a massive task."
The CSIRO approach to tightly linking documentation with system development
was recognised very quickly as a potentially revolutionary solution to a
There are two main components to the CSIRO approach - task modelling and
natural language generation.
"A manual is essentially a guide to doing tasks using a tool - whether the
tool is a machine or a piece of computer software," says Dr Paris.
"The better a task is understood in terms of the steps involved in
completing it, the easier it is to describe those steps in a manual."
CSIRO has developed tools to model tasks so they can be broken down into
their component steps and analysed. CSIRO software can capture task models
from specifications, interaction diagrams, text based scenarios or live user
"As a user interacts with a piece of software, our tools can be recording
all the steps they take," says Dr Paris.
"By capturing every action and response, we can ensure that instructions do
not leave out essential steps or assume knowledge on the part of the user."
Task modelling can also be applied during the software development process
to improve the quality of the product. For example, analysing the results of
task modelling may reveal that a particular task, say sorting a list, can be
done in less steps than originally conceived. This makes life easier for
programmers, designers and, most importantly, users.
The second component of the system is natural language generation - which
simply means the creation of comprehensible text from task models.
"We are developing approaches to generating instructional text that is as
easy to read as text written by a professional writer," says Dr Paris.
"We don't aim to replace writers. Technical writing is a complex task best
done by humans. However, generating instruction sets that are tightly linked
to product functionality is one component of technical writing that can be
tedious and sometimes error-prone."
"Our aim is to automate this part of the process with supporting tools so
writers can concentrate on more challenging requirements such as product
features, context and applications."
Another benefit of this approach to manuals is that updates become much
easier. Simply adjusting the task model allows the new instructions to be
generated in a fraction of the time it would take to rewrite a section of
Dr Cécile Paris 02
cecile.paris at csiro.au
Tom McGinness 02
tom.mcginness at csiro.au 0419 419 210
Images are available for this media release at
CSIRO Mathematical and Information Sciences
Locked Bag 17, North Ryde NSW 1670
Building E6B, Macquarie University, North Ryde, 2113, Australia
T: (02) 9325 3227, F: (02) 9325 3200,
M: 0419 419 210
E: tom.mcginness at csiro.au
W: www.cmis.csiro.au www.csiro.au
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the ASC-media