Technical Writing

This blog is about expository writing—explaining things—but a headhunter technical recruiter recently asked me what a technical writer does, and my answer was the germ for this post. Technical writing is a subset of expository writing, but it’s a pretty large field. Here are my thoughts on the subject.

Technical writing consists of four main writing-related activities; two main ones, and two more generic activities.

Writing instructions. This, I think, is what most people think of when they think of tech writing. The readership is people who don’t know how to do something, want to be able to do it. I tell people it’s “Put tab A into slot B.” It typically looks like a paragraph telling what’s to be accomplished, then a set of steps, numbered, with an illustration for each step. Repeat as necessary. You generally see a cover page of some kind, maybe a table of contents, and sometimes some sort of reference (appendix) in the back. When you write instructions, get someone to follow them! Watch them make mistakes. The mistakes show what’s wrong with the instructions. Fix the instructions.

Describing progress. The main readership of this material is colleagues and people who are checking up on what’s going on; managers, auditors, regulators. I suspect more tech writing is this activity than any other. Projects, especially large ones, especially software development, especially when someone is checking up on things, are the arena for this part of tech writing. Even a project as small as building a deck on the back of the house uses this kind of documentation. You need a description of the deck, a bid from the contractor, plans, a bill of materials, and the invoice. Those are all technical documents. Build a bridge, rocket, or office building, and you have those documents in spades. The description becomes specifications or requirements, for example. In the financial industry, banks have to create descriptions of several stages of their software development projects, partly to convince auditors and regulators that the bank is being responsible in the handling of customers’ money. Even the regulations are technical documents. These descriptive documents have to describe everything. Think detailed lists of requirements, records of meetings where people decided what to do,  detailed lists of tests, reports of the test results, reports of reviews of the computer code to demonstrate there’s nothing malicious in there, the list goes on and on.  Most of these documents aren’t very glamorous, but they can be important. What if the tech writer had been careless describing the contents of the Apollo 13 space capsule? They used that information to figure out a way to scrub carbon dioxide out of the air, saving the lives of the entire crew!

Helping marketers. I think I’ve said before that tech writers regard all marketing people as insane. But technical things need to be sold, too, and described both convincingly and accurately. White papers, proposals, grant applications are all documents whose purpose is to sell something, and they need to be accurate. Tech writing is the part that makes sure that brochure is telling the truth.

Editing and proofreading. Over the years I’ve checked restaurant menus, résumés, newsletters, ads, brochures, even kids’ reports for school. Many people are careless or unskilled about the mechanics of the language, and the wise get someone to look over their work. Tech writing is helping people not look dumb.

Maybe you’re a tech writer reading this. Did I leave anything out?