Robert N. Phillips
CEO, Lasotell Pty Ltd.

Why does management in general and even technical people at the coal face seem to question the value of technical writers? Typically, they question technical writers’ value because past experiences, observations, and rumours have given the feeling that technical writers were not up to expectations. On the other hand, many of us realise that if a technical writer is properly matched to the document development environment, one writer can support a number of engineers and free approximately 20%-30% of each engineer’s time, which can then be focused on the technical component of the task. That value should be enough to please any project manager. However, the key is in the words “properly matched.”

In our organisation we classify people (aspiring employees and contractors) who call themselves “technical writers” into three broad categories.

  • Production “Writers”—these people take material that is completely finished in all respects except for final formatting for delivery and may run a spelling check, add headers and footers, print, copy, package, etc.
  • Technical Editors—these people incorporate a wide range of skills. At the bottom end, the editor can take material that is essentially finished, as far as the author is concerned, and edit for grammar and general style. At the other end of the scale, the editor can take the first or second draft from the author and work with the material in every respect, occasionally add to the content by providing comments and ideas, etc. The difference between the top and the bottom of this category is largely the amount of domain knowledge the person possesses in the relevant field.
  • Technical Authors—these people create material from scratch. They act as ghostwriters—they do their own research, write their own material, edit it (or pass it to someone in Category 2), and deliver it to the “owner” for content review.

This categorisation is very important given that we also classify the documentation development environments into four categories.

Documentation Development Environments

The vertical label means the writer needs increasing amounts of domain knowledge to cope, and the horizontal label means the writer needs increasing amounts of writing and tools skills to cope.

Standard Output: everyone wants standard output, but the conditions necessary to produce it are seldom appreciated and hence rarely achieved.

Magic: characterised by chaos and garbage in, but a Standard Output product is required. Magic is probably the worst development environment because it is characterised by the perception that the documentation is just a nuisance that has to be written with the least amount of effort from everyone involved in “real work.” These environments are also typified by people always knowing, after the fact, how to develop documentation better next time, but never do.

Highly Structured: dominated by the complexity of the deliverable document. Highly Structured is an environment where mature processes are required if you want to deliver the product without losing your sanity or your company or department profit margin.

Nightmare: any job that has been left to a time when it is virtually impossible to provide the amount of information required at a credible standard. The typical response is to throw more people at the job. (Wrong—you actually have more chance of pulling the job off with fewer, thus clearer thinking, heads.) You need a SWAT Team (but Heroes do not come cheap).

Properly matching the capability of the writer to the development environment can go a long way to ensuring the management’s and technical staff’s expectations will be satisfied by the skills of the writer tackling the job. Naturally, properly matching the writer and the environment always produces a better document than would otherwise be achieved.