The Documentation Scene

by John Mobbs

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:

  • What are the essential characteristics of a successful document?
  • Should the document be produced to a recognised standard?
  • Why should the documentation be “designed“?
  • How useful can hypertext be in the current project?
  • Would engaging a documentation consultant help me avoid producing documents which cannot, later, be transferred to an enhanced system without expensive and unreliable conversion.
  • What are the benefits of producing documentation “properly”?

Essential characteristics of a document

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.

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.

The need for design

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

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.

A word about hypertext

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:

The technical author

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?

The case for using a professional author

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.

What to expect from a documentation consultant

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:

The form of the finished document

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.

A cheaper way?

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.

Minimising the cost?

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.

The added-value components of a document

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 level of client commitment

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.