Shanghai Tech Writer

Several days ago, I wrote about the Vita-Mix Getting Started Guide and commented on how pretty the guide is and the appeal of adding color and graphics to documentation.

Today, I’m going to take one small paragraph from the getting started guide and dissect it according to NI Style. At National Instruments, we write our documentation in a very unique way, almost like a new language that’s not quite English. I don’t have a reference point regarding what style guides other companies and technical writers follow, but I would presume there are some similarities as well as differences.

The following note is taken from the tropical fruit smoothies section of the Vita-Mix guide. I don’t say “recipe” because the getting started guide isn’t just a recipe book. It combines both how to to operate a Vita-Mix as well as prepare yummy drinks/desserts/soup.

NOTES/HINTS:

We¹ recommend using brown-spotted bananas for the best² flavor³. These⁴ can⁵ sweeten a drink enough⁶ to eliminate the need for sweeteners. Treat⁷ leftover⁸ with lemon juice or a fruit-freshener. Place⁷⁹ in self-sealing plastic bags and refrigerate or freeze for later use. Use⁷ fruit as it is normally¹⁰ eaten. Never add the peels of pineapples, bananas¹¹ or oranges to fruit drinks.

According to NI Style:

1. We can’t use “we” in documentation. Who’s “we”? We can’t say “It is recommended” either because that would be passive voice. Instead, it should be “National Instruments recommends that you use” . . . or in this case, it should be “Vita-Mix recommends that you use . . .”
2. We can’t use words like best, better, easy, easier, simple, and good . Who’s to judge what’s best, better, good, easy, difficult, simple, and so on? What do you mean “best flavor”? Can you define that specifically?
3. Best flavor of what?
4. What’s “these”? The flavor? The banana? Or the “brown spots”?
5. Can or do? “Can” implies possibility. In documentation, we have to very careful about distinguishing between something than can happen or does happen. I have never tasted bananas that aren’t sweet, so if we’re talking about brown-spotted bananas, they should be super sweet. In which case, adding bananas does sweeten a drink, but it might not be “enough” which leads to . . .
6. How much is “enough”? Isn’t that kind of subjective depending on people’s taste preferences?
7. No subject declared. Who’s doing the action? Sometimes it is okay to just use the verb form without subject, but we try to be as precise as possible by adding “you” infront of the verb. “You treat leftover” and “You place” sound funny but we rather be precise than unclear. This can go either way.
8. Leftover what? Leftover bananas or leftover drink?
9. Place what? The fruit-freshener? The lemon juice? Or the leftover?
10. Same as comment #2. What does “normally” mean? How do you normally eat a fruit anyway? Who’s to judge what’s normal and what’s not? Where I come from, I eat fruits only if they are washed, peeled, pitted, and cut in bite-size pieces. My husband on the other hand eats them as they are, peels, pits, and seeds. Who’s considered normal?
11. Missing a comma here.

This is all I can come up with. I’m sure my colleagues will find a few more to add to the list. So how would this note section look like if it was written by an NI technical writer?

Let me try:

Vita-Mix recommends that you use brown-spotted bananas to enhance the flavor of fruit drinks. Brown-spotted bananas sweeten a drink so that you don’t have to add sweeteners. Treat the leftover bananas with lemon juice or a fruit-freshner. Place the leftover bananas in self-sealing plastic bags and refrigerate or freeze for later use. Never add the peels of pineapples, bananas, or oranges to fruit drinks.

I’m not even sure if I got it right according to NI Style. My colleagues would probably write this section a little differently. They might add a few more sentences and use different words. Other technical writers following their company style might write this section entirely differently.

In any case, whatever we come up with may not be Vita-Mix style nor user-friendly style. You as a reader who’s not in the technical writing profession might be thinking, “Heaven’s sake, this is just a note that nobody is going to read! Who cares! I wouldn’t have noticed if you didn’t point them out!”

This leads to the question of what the purpose of style is really for. Style is a guideline technical writers follow so that documentation reflects a certain order of precision, consistency, and perfection. The technical writing profession is an art and technical writers take great pride in doing what they do, even if nobody else cares.

(No Ratings Yet)

 Loading ...

  Subscribe to RSS feed       Subscribe via e-mail