The documentation scene
Funny thing, documentation. Ought to be easy enough, surely?
So why the disappointing results? What IS the elusive spark which distinguishes
the professional author from others who put their hand to the pen (keyboard)?
Let's look at some pertinent questions under the following headings:
The documentation
The documentation which accompanies a product is often the only means by
which a user can realise the product's full potential. Yet at the same time
it is often regarded as an afterthought, a necessary evil, which must be "knocked
out" with as little effort as possible. Some fundamental questions include:
For a user document to be successful, and therefore, ultimately acceptable
to the customer it must be prepared well enough that it:
- accurately targets the intended readership in terms of language, concepts
and previous knowledge of the subject;
- develops the material at a depth and pace which is consistent with the
intended reader's level of intelligence without being patronising;
- maintains a consistency of terminology to avoid confusion;
- presents a writing style with which the intended reader can find a rapport;
- sustains a tone which is consistent with the supplier's corporate image;
- describes complexity and detail without being intimidating;
- enables topics at random to be found easily;
- provides procedural instructions which are complete in every detail and
which work in practice.
A document exhibiting these characteristics brings us to the question of documentation standards.
Much documentation is not produced to a recognised standard although this
seems to be changing. On a smaller scale conformance to local house styles
and document structure is often required. A company which has, or is seeking,
ISO9001 registration will typically use a standardised set of headings to
govern the design of its user documentation.
Good documentation systems, like any other systems, need to be designed.
It is not uncommon for documentation to be written, sometimes mountains of
it, without any coherent structure into which the documents can fit. The result
is a haphazard and impenetrable mass of knowledge which cost a fortune to
produce and which is utterly intimidating.
Documentation design addresses such questions as document hierarchy and the
levels within it at which certain kinds of information should be carried.
The design philosophy will be a top-down approach.
In an ideal world the user documentation would be designed along with the
rest of the user interface. The technical author or the documentation consultant
would be involved in the user interface design and would make an input on
questions such as screen/printout formats and the preparation of Help text.
If it is decided at an early stage to produce a system overview then this
can double as, or be modified into, an effective sales document. In this way
it is possible to avoid writing essentially the same document twice.
Documentation design is one element you should be able to expect from a professional
technical author.
The benefits of professionally written documentation include:
- Improved reputation in the market
- Higher satisfaction level among existing customer base
- Increased likelihood of repeat orders
- Enhanced new sales prospects
- Reduced cost of on-going support
- Designers' time released for "proper" research & development work
- More for competitors to worry about
These benefits should accrue from a contract with
a suitable documentation company.
The use of hypertext is on the increase. Applications and advantages of hypertext
include:
- Situations in which it is important that the documentation stays with
the product throughout its life.
- Support documents for work at a distance from base where carrying bulky
and heavy hard copy is impracticable. Have the file on a laptop.
- Maintenance of a large number of copies where it is important that the
very latest version is always used. Access the only (master) copy via a data link.
- Applications where documents can be updated by downloading.
Hypertext is the documentation medium of the future.
The professional technical author
There is a profession which specialises in technical documentation and where
people earn their living by it - an ISTC Member follows a
Code of Conduct. Documentation, for them, does not compete for priority
with developing the product.
A specialist documentation company will devote their whole attention to the
document and take good care that the finished publication is a lucid and attractive
product. On a slightly broader scale there is much to be gained from documentation
consultancy. Consider the profession under the headings:
Many people who lay no claim to being a author believe, nevertheless, that
they can write. Many can, but unfortunately many can't. What distinguishes a Technical Author from anyone else who thinks they can write?
- a feel for words;
- a concern for verbal consistency;
- an appreciation of tone and style;
- an awareness of logical development and assumptions;
- a command of grammar and vocabulary;
- an enquiring mind with attention to detail;
- the ability reliably to grasp and structure large amounts of information;
- clear thinking;
- imagination;
- rapport with the learning process;
- an ability to anticipate the reader's knowledge gaps;
- awareness of the need for a conceptual framework into which the new knowledge
must fit;
- skill at explaining on paper;
- interpersonal skills;
- editorial judgement.
These are not options; a competent author will have all of these qualities.
Existing knowledge of a particular subject area is less important than the items listed above. Communication is a profession in its own right. What can
you reasonably expect if you engage one of these people?
A technical author should offer:
- A document which imparts a discovery experience rather than being simply
a listing of the available knowledge.
- Some guarantee that the document will not fall below a reasonable standard.
An author's livelihood often depends of the quality of the work.
- Certainty that attention will be given to the document as a project in
its own right which deserves a high degree of skill and application.
- A fresh pair of eyes, linked to a mind accustomed to assimilating new
material and questioning its integrity before the customer does so.
A good case can be made for engaging a service which
specialises in technical authoring. Documentation is their business; they
devote their whole attention to it and take good care that the finished publication
is a lucid and attractive product.
The documentation consultant is a useful animal. The essential quality he/she
can bring to a project is a clear grasp of documentation system design. This
will then set the course for the documentation to pursue.
The contract with a consultant should be to secure sound advice on:
- Documentation hierarchy.
- Levels within which documentation should be self-contained.
- A system for document revision control.
- Protection against document related litigation.
- Caution against steps which would render the documents incompatible with
additional processing at a later date.
- Pros and cons of the different documentation tools available.
- The factors to be considered when developing a House Style.
- The minimum requirements of an Electronic Publishing or any other kind
of document processing system being contemplated.
- All aspects of document security and archiving.
- Alternative possibilities for document presentation.
The consultant should also have the ability to deliver the required service.
The contract
When considering embarking on a documentation contract, there are several
essential factors to consider:
Essential questions here include:
- What presentation will be most cost effective in imparting the required
knowledge?
- How can I ensure it stays with the product?
- How can I ensure that updates are included?
- Will the document fit into the product packaging?
- Is a hypertext presentation going to be useful?
Printed and bound hard copy can be formatted to a default style or to the
client's own style. It would normally be typeset incorporating a pre-printed
front cover to fit the client's corporate image if required.
All copy is, invariably, prepared electronically and so can be presented
as text and graphics files for further processing by the client's own Electronic
Publishing System. In practice, the greater the proportion of graphical content,
the greater the cost.
Yes, you can do more cheaply but whether you maintain an appropriate level
of quality is open to question. Your customer will judge your documentation
as they will judge your product. Unless the documentation is accessible and
comprehensive no-one will ever get the best from your product and your reputation
may suffer.
It is sometimes tempting to get the designer to prepare the document simply
because the knowledge is there; it "just needs putting on paper". There are
at least three problems with this approach:
- The designer is a highly trained person who could (hopefully) be more
gainfully employed on "proper" research and development work.
- It misses the advantage of having a fresh pair of eyes looking at the
project.
- Many analysts, programmers, engineers and designers lay no claim to being
good at writing; indeed many of them dislike it and try to minimise the
time they give to it.
Using this approach the essential characteristics which lead to a good document
are likely to be missing. Even using a Technical Author it is possible to
cut corners. Aspects of documentation which suffer when corners are cut include:
- Topics for which the author cannot get adequate information quickly tend
to be fudged. The reader is then left confused.
- Sections of text or illustrations are copied into other places without
detailed examination and amendment to ensure that they are correct in
the new context.
- Newly thought out illustrations do not get created.
- Explanatory material, which might help the reader to realise greater
potential from the product than the procedural instructions cover, might
be missed out altogether.
ISTC Members do not produce cheap, corner-cutting work. Cutting corners is
not a recommended way of reducing cost; there are better ways.
Some steps can be taken to minimise the cost but some misfire. What is useful?
- A realistic awareness of the cost of the options. Producing
the document in-house can incur substantial hidden costs which can turn
out greater than the contract price of a professional author.
- Getting the balance of the document right at the beginning.
If this is not done then a disproportionate amount of work will be put
into some, perhaps less important, parts of the document.
- Keeping to the original documentation plan. Changing
the design or scope of the documentation (or the product) after the first
draft significantly increases the cost.
- Pictures. If the document contains halftones and/or
colour and is to be printed on offset litho then the artwork and filmwork
tend to be expensive.
- Making source information available. Deciphering unclear
or confusing source information is time consuming. It can be more economical
to give the author access to (possibly expensive) personnel who can
explain a topic lucidly and concisely. Having existing documents, screens,
graphics, reports, etc on diskette also saves time.
A document has value added by each stage of processing. What aspects of the
added value justify their cost? What aspects should be considered?
- Well designed document. If the document and the overall
structure into which it fits are well designed then development, maintenance
and enhancement can all be very cost effective. Design economy is false
economy.
- Imaginatively written text. An accessible document with
which the user is comfortable can minimise the cost of customer support.
- Illustrations. Some illustrations are very expensive
to produce but many are invaluable. Care should be taken in assessing
the cost effectiveness of every individual illustration in the document.
- Typesetting and imaginative presentation.
Superficial attractiveness bestowed by the use of desktop publishing is
no substitute for well prepared content. Pretty presentation only adds
real value if the content is good.
- Personnel time. There are always occasions when an author
needs an explanation of a topic. These times
need not necessarily be expensive.
The time commitment which the client may expect to make will normally occur
in two phases. The first is in providing the information and the second is
in vetting the draft document.
Professional authors use rapid and sophisticated techniques of information
gathering so as to minimise the amount of the client's time which the work
requires.
A client would be asked to provide any existing documents relating to the
project and also any functional specification, sample reports, screen dumps
and any other graphics material for reproduction. It would be helpful if the
text could be in ASCII and the graphics either as directly reproducible hard
copy or output on diskette from a drawing package.
|
