On Technical Writing

“If we want to go to the moon again, we’ll be starting from scratch. All of that knowledge has disappeared."Unknown NASA engineer to David DeLong.

At its simplest, technical writing is the preservation of knowledge. We collect what's in people's heads, written on scrap pieces of paper, recorded in interviews, or written in notes to themselves or their co-workers. It would be easy work if that was all we did.

"That's where all the rest of scholarship starts, Garion. All the books in the world won't help you if they're just piled up in a heap." David Eddings, King of the Murgos.

Technical writers and librarians do similar work: what librarians do for collections, tech writers do in books and articles. We organise the knowledge, and make it accessible. We work in many fields: we preserve information from the most technical aspects of brain surgery to the simplest hobbies. My own field is the more technical aspects of computer work.

We translate. Most technicians (be they surgeons, engineers or hobbyists) assume prior knowledge when they explain what they do. It's normal, they've studied so hard and so long that they've forgotten how difficult a technique was when they did it the first time. The technical writer has to translate the jargon used, and explain the technique in enough detail for her audience.

Her audience. See? Now I'm using jargon. The 'audience' is the intended reader. If the writer is producing an article on diabetes for "Lancet" (a medical journal intended for medical professionals), she can assume the reader knows and understands the interrelationships between insulin and glucose. If she's writing for "Diabetic Living", a magazine for diabetic patients and their families, she has to be prepared to explain the relationship, but can expect the reader to know the terms 'insulin' and 'glucose'. If she's writing a piece for the Sunday supplement of the local newspaper, she'll have to explain even those terms.

We also organise. We arrange information in useful pieces. Perhaps an article, such as this one. Or a book. If we organise it into a book, we decide what sort of book. Is it a chatty non-fiction book, suitable for summer reading on the beach, in which we break up a complicated issue into easy to digest pieces for the layman? Or perhaps a tutorial, designed for student engineers, explaining the various types of concrete and where, and how, they might want to use each type? A handy reference for the geologist out in the field, listing which plants native to the mesas of Western USA indicate which subterranean mineral deposits?

There is a lot of detail to doing our job well. We need to think not only of the content, but the format: would that roving geologist prefer a small book containing only the plants of the mesas, or would he like a tome covering all the relevant plants on the North American continent? Or perhaps one of each: one to carry in his car while he searches for deposits, and one to study in his office.

Within the book (or the article), we strive for clarity and concision. We try to be accurate, and to avoid ambiguity. We try to explain our topic so that it can be understood by a variety of human learning styles, yet without repeating ourselves. And we try to be at least somewhat entertaining, or at least easy to read, while doing all that.

It's a challenging job, but one I enjoy and consider important.