Technical Writing’s Big Secret

How I Did It by Victor FrankensteinFrom time to time a manager or engineer asks me the following question: “Most technical writers don’t have much technical training. How do they write documents for products they don’t understand?”

The answer is, “They don’t. If you don’t understand it, you can’t explain it.”

The whole point of a technical document is that it tells the reader how to use a product. This can only be done by a writer who knows how to use the product.

Sure, if the product can be used successfully by a technically unsophisticated reader, the manual can be written by a technically unsophisticated writer. It helps if the writer has enough background to understand the designers’ technical jargon, but this isn’t absolutely necessary. Someone is going to have to translate it for the layperson anyway, and it doesn’t have to be the technical writer.

But things get complicated when the readers are sophisticated, and use the product in a sophisticated way. For example, a statistical software package cannot be adequately documented by someone who knows nothing about statistics. An integrated circuit cannot be documented by someone who doesn’t understand circuit-board design.

People sometimes assume that “being technical” is a personality trait. It isn’t. Only relevant training and experience counts. I’m very technical when it comes to digital electronics, but I know nothing about biochemistry. I once had a summer job in a biochemistry lab. I learned how to run the autoclave and perform other tasks, but I never grasped what the researchers around me were trying to learn, or how their experiments achieved this.

The Big Secret

The big secret in technical writing is that most of the harder documents aren’t written by the technical writers at all. In fact, many “technical writers” never do any writing. Instead, the drafts are written by engineers or marketers. The technical writers perform editorial functions and provide publications services—copy-editing, desktop publishing, review management, and so on.

The phenomenon of technical writers who do not write is so pervasive that I once interviewed a technical writer—a man with 15 years of experience at a prestigious high-tech company—who was visibly startled when I told him that, in my group, we wrote documents from scratch. He’d never heard of such a thing.

Job titles betray no clue about a technical writer’s qualifications. Regardless of the writer’s background, background, the title is “Technical Writer” or “Documentation Specialist” or even the vaguely Orwellian “Information Designer.” Or possibly “Desktop Publishing Specialist” or “Secretary.” But managing your documentation projects requires that you know who is capable of doing what.

The problem is that the demand for technical writers greatly exceeds the number of technically trained people who prefer writing to other work. Non-technical folks have been sucked into the vacuum. Often these are college graduates with a liberal arts background. They may be excellent writers on their own turf, but nothing in their training prepares them for the world of high-tech.

Who Writes the Draft?

The first draft must be written by someone who can understand the product. There is no getting around this. If you can’t find a technical writer who can do it, someone on your technical staff has to.

The technical competence of your technical writers determines your entire plan of attack. Writers who are technically competent should be given the entire documentation task, so you can free up more design resources. Ideally, the technical writer should be brought in early, so the documentation can take form well before it is released to customers. This aids both the design and the selling process. It’s usually possible to have a mostly-final draft well before the product is shippable.

If you don’t have writers who can write the draft, the task must be assigned to someone who can. This should be planned for from the outset. Writing is difficult and slow. It cannot be done in an overworked engineer’s “spare time.” This requires planning and management.

A technical writer should be assigned to maintain the document. My rule of thumb is that half the labor of creating a document goes into writing the rough draft, and the other half goes into smoothing it up: editing it, laying it out, correcting it, and getting it out the door. This means that the not-so-technical writers can still shoulder half the burden of even the most insanely technical product. Also, while writing the rough draft is painful, the endless series of revisions and small corrections that follows is even worse. Technical writers are used to it.

Finding Technical Writers Who Are Technical

In the high-tech industry, there are three categories of technically inclined writers.

  1. Engineers who prefer technical writing  are as rare as hens’ teeth. I am one. I’ve met three or four others so far in my career. Such writers have great advantages. Simply by surviving a college engineering curriculum, they have demonstrated that they can absorb difficult material from textbooks and mumbled lectures, and ought to be able to bring themselves up to speed quickly on a new design or new technology.
  2. Engineering technicians often make great technical writers. They are comfortable around engineers and have a lot of applicable hands-on experience. They know they don’t have the same training as the engineers and aren’t expected to, so they tend to be up-front about material that goes over their heads.
  3. Experienced technical writers who have picked up skills on the job. The difficulty lies in distinguishing them from writers with  shallower experience who perform well at job interviews.

The Toaster Test

I used to test candidates by asking them what topics should be covered in the operating manual for a toaster. At first, I thought this test was so easy it would be worthless, but it turned out that many candidates who were well-spoken in interviews had no grasp of the fundamentals of clear writing.

For the record,  I figure that a toaster manual ought to contain the following sections, many of which would be no more than a paragraph in the finished document:

      • Theory of operation (what a toaster is for—no more than a sentence unless you expect the product to be used by aliens)
      • Unpacking and setup
      • Purpose of each control
      • Operation
      • Safety
      • Cleaning and routine maintenence
      • Things that shouldn’t be cooked in a toaster (if not covered under “Safety”)
      • Recipes, if by some miracle you can think of something new and tasty that would increase the reader’s enjoyment of the toaster
      • Troubleshooting, which will be on the level of, “It works better if you plug it in” unless the design is seriously flawed.
      • Specifications: voltage, amperage, physical dimensions, color choices (though it’s a little late now).
      • Contact and warranty information.

Competent technical writers can dash off something like this in a few minutes. Some can dictate one without stopping to think. But I received some efforts that were truly ghastly.  Not in terms of spelling, punctuation, or sentence structure. These were perfect. It’s just that none of the sentences expressed anything that a reader would have cared to know.

Speaking of tests, I know some people who screen resumes and cover letters by looking for errors in punctuation and grammar, and disposing of anything that isn’t 100% perfect. This is pointless. Everyone in the publishing industry knows that people are terrible at finding errors their own work; that’s what reviewers and copy-editors are for. The only thing that typos in a resume and cover letter mean is that the writer was working alone.

You may want one anal-retentive person on your team whose job is to find such errors, but if you saddle yourself with an anal-retentive writer, good luck ever getting them to finish a project.

Conclusions

    • Drafts of technical documents must be written by someone sufficiently technical to use the product.
    • If your writers aren’t this technical, some or all of the manual must be written by someone else.
    • Knowing the technical limits of your writers will allow you to assign the chore of writing the first draft correctly.

3 thoughts on “Technical Writing’s Big Secret”

  1. I didn’t realize how old this post was until after I got done with it – 13 years! But the funny thing is all of this information is still relevant I would say.

    I like the ‘Toaster’ concept – I may use that one some day – thanks!

    Matt Jarvis
    Eugene, Oregon

    1. Matt, thanks for writing!

      Yes, I’m often struck not only how fundamentals never change, but often how details remain the same, too. I was editing an /etc/hosts file on a server with vi the other day, and was struck by the fact that I’d first done this very task 30 years ago. And it’s even more true when it comes to dealing with people.

      Robert

      1. Hi Robert,

        This is a great article.

        Though I find myself in the same boat as Matt (reading this piece nearly 15 years after the fact!), it does a wonderful job explaining what a Technical Writer does, and what strengths or skills are, or are not, to be expected given the varied backgrounds and experience levels of many different writers. Thank you for posting this (even after all this time!).

        Question: Is the typo in final block before “Conclusions” intentional or merely a rare example of pure irony? I’m dying to know!!!

        If it is intentional, then bravo, sir; it’s an amazing Easter egg.

        Phillip Cheney
        Documentation Specialist
        IMPLAN Group LLC.
        Huntersville, NC

Leave a Reply

Your email address will not be published. Required fields are marked *