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

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.

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!

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.

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

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

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

Matt Jarvis
Eugene, Oregon