Monthly Archives: July 2012

Product-Oriented Writing: "Windows" Shopping

So, now that I’ve exposed product-oriented writing as the hack tool that it is, you might wonder why anyone would write this way in the first place. The answer: It’s the obvious way. Think about it. You launch a product, and there’s the interface, so you write about it. There’s the File menu; you write about it. There’s the Edit menu; you write about it. There’s the Tools menu; you write about it. Also, the product designers love you if you sexy up the interface in the user guide, so they smile at you in the break room, and you go back to your desk thinking you’re the best tech …

Continue reading

Posted in Uncategorized.

Product-Oriented Writing: The Problem

Here’s the problem with product-oriented writing: Users hate it. Why? The user wants something–that is, some thing, a credit report, a completed tax return, the zip code for Kodiak, Alaska— from the product. The product is the tool, and the product interface is the veneer of the tool–a series of screens and windows that appear and disappear as the user tunnels in to get her goods. So you can see how a document that describes the interface in ground-breaking detail sidesteps explaining how to really use the product. I know what you’re thinking: Describing the interface is explaining how to use the product. Right? But no. To dust off a …

Continue reading

Posted in Uncategorized.

Put Your Writing on a Diet

The Writer’s Diet test is a nifty tool for gauging the “weight” of your writing. I used it on two of my blog posts, and I’m happy to report that one post registered “lean” and another “fit and trim.” Put your text through its paces and let me know if your writing needs to drop a dress size or two.

Posted in Uncategorized.

Ten Tip-offs of Product-Oriented Writing, Part 2

In technical documents, some writers (try to) explain how to use a product by describing the product’s interface, a method–if you can call it that–I’ve named product-oriented writing, or POW. In my last post, I listed some signs of POW. Here are a few more: The text uses the techie version of interface names: dialog instead of dialog box. The document includes a section called something like “Document Conventions” that glorifies each element of the interface with a picture and a description. Procedures pilfer names of interface parts for the instructions themselves, thus creating odd redundancies: Enter a modification description in the Modification Description text box. Headings imply that using the …

Continue reading

Posted in Uncategorized.

Ten Tip-offs of Product-Oriented Writing, Part 1

When a document describes a product’s interface before explaining how to use the product, I call that product-oriented writing, or POW. The other day I trotted out an analogy to POW that included a sick person, a receptionist, a verbose office assistant, and an ephemeral doctor. (I’m sure the analogy is clear. If not, read the post.) So what is product-oriented writing anyway? In short, it’s a guided tour of the product’s front-end, a method of writing that’s oh-so-common and yet oh-so-useless. You probably want examples. In 45 seconds of extensive research, I found some online. (I don’t know who authored these gems, but I withhold judgment on the writer. …

Continue reading

Posted in Uncategorized.

POW! How To Frustrate Your Users and Make Yourself Useless, One User Guide at a Time

Here’s a scenario for you: You’re sick. You woke up with what you think is an ax lodged in your skull, and every time you swallow, it feels like knives line the back of your throat.  Your eyes burn with fever. The thermometer says 102. You drink some OJ and think about the presentation you’re supposed to give tomorrow morning. If you stay home today, you might feel better in the morning, but you’ll miss the only time you have to put the finishing touches on your PowerPoint. If you rally the strength to get dressed and drive to work, you’ll be ready for your presentation by tomorrow morning, but …

Continue reading

Posted in Uncategorized.

A Good Time Was Had by All

When I became a tech writer, all the writing classes I took and all the books I read said that the passive voice is bad, bad, bad. So I never used it. But then, after writing documentation for several years, I noticed that sometimes, occasionally, maybe just once in a teensy-weensy while, to keep the user’s focus on the right subject, a sentence demanded the passive voice. Then, when I began exploring plain language, I was shocked–shocked!–to learn that even some plain language style guides recommend using the passive voice for the same reason. Hence this series of blog posts on where plain language, technical writing, and the passive voice …

Continue reading

Posted in Uncategorized.

Mistakes Were Made. Others Will Be Blamed

One thing the passive voice loves to do is dodge responsibility. Consider this sentence: A graph and a timetable can be included in the report. Now think of context. If the sentence is part of a paragraph describing a report’s information, the user might wonder: That’s nice to know, but will it? But if the sentence is part of a procedure telling the user how to create the report, the user might wonder if, and how, he can include the graph and timetable in the report. So what problems do statements like these create for users specifically? Let’s build from the context. In describing a report, a sentence like A …

Continue reading

Posted in Uncategorized.

We’ll Be Back Next Week!

Happy Independence Day! Write2Help returns next week to finish up the discussion on the good, the bad, and the ugly about passive voice, and to launch a series on avoiding system-speak in your documentation. In the meantime, think plain; write plainer.

Posted in Uncategorized.