If I had a dollar for every time I’ve tried to answer this question I’d be able to afford that multi-month trip to New Zealand that’s on my bucket list!
I have this vague memory of a Wonder Years episode in which Coach Cutlip asks the class what a jock strap is for. To me, the answer to that question is as obvious as the answer to the one about technical writers. I wasn’t sure of the exact wording of the answer that Kevin gave Coach Cutlip, but the wonderweb offered this version. “The jock strap, sir, is a particular kind of strap, made out of a strap-like material, used exclusively for the purpose of jocks.”
So for the purposes of this article, I’ll answer the titular question thus: a technical writer is a particular kind of writer, made out of writer-like material, used exclusively to write about technical stuff.
Shaking the shackles of parody and rephrasing aside; a technical writer receives information about the subject of the documentation, organizes and filters the information, and produces formatted, illustrated, maintainable documentation about it that is suitable for the intended audience.
Let’s regard that last sentence as some of the initial raw information that a technical writer receives. Here is what he (I’ll use “he” since I’m a “he”) might produce, after asking the right questions.
Role of the Technical Writer
Executive Summary
A technical writer acts as a translator between the subject matter experts (SMEs) and the audience(s) identified in the documentation project statement.
Documentation Production
The following paragraphs show the stages of documentation production. They may vary slightly in order to fit in with the manager’s preferred style of project planning, execution, management and reporting.
Documentation Planning
The writer interviews the SMEs and the project leaders to determine the objectives of the (documentation phase of the) project. He also assesses the audience(s) and the conditions under which they will access the documentation.
Using that information, he will recommend
- the format and composition of the documentation as well as the medium (or media) on which it will be delivered to the audience.
- the use of graphics (photos, statistical charts, matrices, flow diagrams)
- the tools to be used to create the documents and the components of those documents.
He will also create an estimate for the documentation, broken down by individual publication or topic grouping (according to the project manager’s specifications).
Some technical writers are able to recommend the types of stationery to use for the various documents, although in many large corporations the Communications Department will do that.
Authoring (Writing) the Content
The technical writer will acquaint himself with any house styles and publishing standards that the organization has, and determine the required tone. (Government policy documents convey a far different tone from, say, the baggage and cancellation policies of Westjet in Canada or EasyJet in the UK.)
He will then write the first topic group or perhaps complete a sprint, and present it for review, to ensure that the layout, style, tone and other mechanical aspects of the writing are acceptable.
Once any necessary adjustments have been made, there then begins a cycle of SME interviewing, writing, SME and peer review, editing, and if practical, user testing. During this iterative phase, checks are made for consistency of the above-mentioned mechanics. If appropriate, text will be structured to facilitate reusability.
Throughout the project, careful attention will be paid to version control.
Publishing and Storing
When the documentation has been signed off, it is promoted to production status and any house publishing standards followed for that change of status, including the deposit of the master copies into a Document Management System or other organization-sanctioned repository.
Software Products Used
During the course of his work, the technical writer may use some of the following.
- (Microsoft) Word, Powerpoint, Excel, Visio, Publisher
- (Adobe) Acrobat, Robohelp, Dreamweaver, Photoshop, Illustrator
- (Other) Madcap Flare
Skills Provided
The technical writer uses the following skills to distinguish himself from someone whose primary function is not writing.
- Intermediate to advanced knowledge of the above-mentioned products
- Interviewing skills; ability to ask the right questions and understand the answers while putting the interviewee at ease.
- Organizational skills.
- Superior knowledge of spelling, punctuation and grammar in the language(s) being written in.
- Superior awareness of the common defects of documentation (e.g., wordiness, ambiguity) and of how to avoid or correct those defects.
Not Exactly an Elevator Speech
That explanation was just over 500 words—definitely not a 15–20-second elevator speech. That initial sentence—a technical writer receives information about the subject of the documentation, organizes and filters the information, and produces formatted, illustrated, maintainable documentation about it that is suitable for the intended audience—is much more suited to elevator talk, but really doesn’t sell technical writing services to a skeptic.
But it wasn’t meant to. I worded it for information, not for marketing. And that’s another benefit of hiring a technical writer—he or she knows when to inform, when to entertain and when to sell. My marketing/selling writing is very weak, so I try to avoid projects that involve marketing. One day though, I will for sure take a “writing for marketing” course and then look for opportunities to hone that new skill.
In the meantime, I’ll continue to provide quality technical documentation to my clients.