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.

8 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

      2. Wow Robert,

        You nailed it. I’ve been a “Technical Writer” for six years. Writers can only write what they already understand or have been shown by the creator/specialist/SME of the subject matter. So many corporate employees believe that a “Technical Writer” should know all/see all/write all WITHOUT any education/learning from the source. “Here’s the product – write every kind of “documentation” we can think of (but haven’t told you). We shouldn’t have to do anything.” Time to wake up folks – The flow of information must come from a creator, down to the project managers, and taught/demonstrated to the “technical writers” before ONE word is written. Tech writers must be provided with a summary training, a demo/test environment from which to observe, and a technical review once writing is complete. Tech Writers should not have to hunt and scavenge for information while you are “too busy” doing other things. Give them a chance to succeed!

  2. I would argue that in today’s environment of “less is more” and giving users “the right information and the right time”, there are a couple of things I would not expect included in the toaster user manual.

    1. Theory of operation (what a toaster is for). I’m going to argue that informaiton belongs in marketing content on the box or on a tag if the toaster is on display. I think it’s reasonable to expect that someone isn’t going to purchase a toaster until they know what it’s for. And I would hope the consumer isn’t required to tear open the packaging to go read the user manual (that we know most people don’t look at until they have a problem) to find out why they purchased this appliance in the first place. 🙂

    2. Specifications. Again this is content that belongs on the box and marketing tag for display. Consumers need to know this information before making their purchase. As a consumer, I wouldn’t be too happy if I made a purchase only to get it home, unpack it, and then find out it doesn’t meet my electrical specifications. 🙁

    3. Safety and things that shouldn’t be cooked in a toaster should come from the legal department, not the tech writer. That content often has to be written in a specific way to cover the company in a legal suite. This content absolutely has to be included in the documentation, but the tech writer should get it from legal.

    4. Troubleshooting “It works better if you plug it in”. I’m going to guess that was just a cheeky way of saying “Try plugging the toaster into a different 120 volt outlet to make sure the fuse hasn’t been flipped on the existing outlet.” You already covered plugging the toaster into an appropriate outlet under unpacking and setup.

    Just my two-cents worth. I’m one of those experienced tech writers with a liberal arts degree who started out doing IT support and have learned everything technical on the job. And, as an older employee, I find it more and more difficult to find employment because companies don’t want to pay us for all our technical knowledge. Many companies want an (experienced) technical writer at the same pay as an (editorial) technical writer.

    1. Hope,

      Thanks for writing!

      Yes, major specifications need to be on the box! But consider these two points: (1) Boxes are soon discarded by the user, and (2) box designs are sometimes botched, either initially or later on (often when the product is dumped into a plainer box as part of a cost reduction). While it’s a nuisance for a store clerk to have to open the box and fish out the manual to answer a prospective customer’s question, it’s better than not being able to answer the question at all. If my documentation is complete, then almost anything else can be botched, and the customer can still get by.

      Yes, I agree that the safety section typically comes from the legal department. The legal department tends to produce contemptible non-documentation for the safety section, covering the company’s ass without protecting the customer. It’s hard to talk management out of this, and users know better than to expect the safety section to contain anything useful, anyway. My solution is to ignore the safety section, and to embed the real safety information inside the procedures, which is where it belongs anyway.

      Theory of operation: sure, a lot of this should be repeated on the box. But remember that the manual is “The One Eternal Document,” especially if it’s included in printed form with the product. Even if the manufacturer goes out of business tomorrow and its Web site vanishes, the printed manual persists. Most likely, the PDF version will continue to exist on the Web somewhere, too.

      Often, with any product, one person decides to buy it, it’s delivered to a second, installed by a third, and used by a fourth. The sales flyers used to convince the first person to buy the product aren’t passed on down the line. I figure it’s my manual’s job to tie everything together.

      When I was working at a network equipment company, for example, the people in small branch offices would sometimes receive equipment that they hadn’t expected. They didn’t know what it was or why it had been purchased, but they were told to install it and make it go. This happens all the time. And even in better-run companies, people leave or are promoted, and new people take over equipment without the slightest knowledge of what it’s for or how to make it go.

      After trying it several different ways, my preference became a single document containing everything, so you’d find the information you needed on the first try. When the contents were split among half a dozen documents, users often couldn’t find what they needed at all.

      With a consumer product, I might has as many as three documents: a quick-start sheet, a user’s guide, and a reference manual, but the user’s guide would repeat the information in the (soon discarded) quick-start sheet, and so on. With a commercial product, it would more likely be one or two.

      You’d think that this is less important these days, with everything being available online, but many Web sites are poorly structured and maintained, and information can begin to vanish long before a product is no longer in active use. At least a giant omnibus PDF file has every single keyword phrases a user might attempt when looking for information on the product. (Thank god search engines can crawl PDF files!) I’ve often had to do this kind of search to discover information on products that left production just a few years ago.

      Even within the company that manufactures the product, the manual soon becomes a primary source document. It’s far easier to find and study than source code, schematics, or mechanical drawings. So I like it to be as complete as possible across the entire life cycle of the produce, both inside and outside the company.

      Robert

  3. Very good article, but I disagree about flaws in grammar and punctuation. A writer that would allow them on a resume isn’t as sharp as they could be. Sometimes a writer does have to work alone, and it’s unlikely there will be someone on hand who cares more about language than they do. To my mind, flaws in writing raise doubts about the integrity of the product and the organization as a whole.

    1. Well, we’re not going to agree on that one. Getting the actual job is essential. Doing it elegantly is an added bonus. I’d take a talented dyslexic writer who imagines his resume is error-free over any less talented writer: that’s a no-brainer. People who can do minor copy-editing are a dime a dozen. Good writers are hard to find. One might just as well refuse to hire writers with poor handwriting, on the grounds that someone who cared about their craft would have a fine copperplate hand.

Leave a Reply

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