technical author
|
|
|
The work of a technical author |
|
|
|
What does a technical author
do?
The work of a technical author The most important person: the reader What should you look for in a technical author? When should you call in the technical author? Why do you need a technical author? What does a technical author need? What if you can't afford a technical author? |
|
A technical author produces deliverable documentation
of some kind. This may be a book, manual, set of
specifications, web page, script or whatever, with or
without illustrations or multimedia enhancements. What
is common to all these is that something technical is
explained in words. It is the technical author's skill
in explaining something simply and clearly that
produces the final result.
However, before the documentation is delivered, very much more has to happen. The technical author's work can be broken down into four main tasks.
Assessing the documentation requirements A technical author first finds out as much as possible about the intended readership: the readers' work, knowledge and background, and the depth and breadth of the information they require. Once this is done, it is possible to decide what kinds of documents are required, and how they are to be presented to the readers. Collecting the information This is usually the most difficult and time-consuming part of a technical author's work. The information may be in fragments of documentation already existing (on paper or on disk), in computer code, in people's heads or in other forms. I prefer to collect as much information as possible from such written sources as documents and code before conducting interviews. This means that I can draw up a list of specific questions to ask, and avoid taking up more than necessary of the time of busy people. Collecting information is much like scientific research - extracting the hard-to-find, relevant information from much that is irrelevant - which is why I find my scientific research background so useful. Organising the information This is an essential step, because documentation that is not organised according to the user's needs is almost useless. The reader must be able to find what he or she needs without having to hunt for it. Organisation is generally what makes a good manual rather than a bad one. Creating the deliverable If the earlier steps have been done correctly, this is usually the easiest, and sometimes the quickest, part of the process. The technical author presents the information in a clear way using the language most appropriate to the intended readers - non-technical and jargon-free for non-technical readers, and using appropriate technical terms for technical readers. As part of producing the physical documentation, the technical author may also create templates and house styles. Much research has been done over the last few decades into how people read and understand written language, and how to enable them to get the most out of a document with the least effort. A good technical author will make use of this. For some information about this, see Joseph M. Williams, Style: Toward Clarity and Grace, University of Chicago Press 1990. |
|
|
This is
version 2, November 2002.
Copyright © 1999-2002 Richard Burnham
and |