Method

Technical documentation is often produced iteratively by a technical writer gathering information from an expert, formatting it and presenting a draft back to the expert for review. This is often a lengthy process requiring many cycles, which does not always produce good documentation.

The main limitations of this process are the writer's understanding of the subject and the expert's availability and willingness to participate in the process.

Writer's Understanding

A writer who does not understand a subject properly simply reformats information. The end result is a very limited document, in which the expert often sees their writing or spoken words come back in a more obscure form. The number of documents written by technical writers who did not fully understand their subject matter bears evidence to this.

Expert's Availability

Most experts do not enjoy explaining their product to someone who has a limited understanding, especially when the perception is that the writer is there to "get information out of them". This is reasonable. They also often consider documenting their product a lower priority than producing and testing it, which is a real constraint often imposed by project deadlines.

Our solution to these limitations is to learn about the product from all possible sources before gathering information from an expert. Because of our technical background and extensive knowledge in many fields, this learning period is often short even if we do not have specific knowledge of the product.

Even if it does take a little longer, this process invariably results in better documents, since we understand and are able to explain what we are writing about. After the initial learning period we can often work alone, with only the occasional request for an explanation from an expert, which frees them to continue their normal tasks without interruption.

The final result is high quality documentation which has used resources effectively, has a lower overall cost, and greater long term utility.

These documentation methodology differences are summarised below.