On Coconut Macaroons and Technical Writing

The failures of technical writing often fall on the end user, a mindset that needs to change.

Welcome back one and all. 

Often, I am asked to submit examples of technical writing to potential employers or freelance clients. My response is always the same: I send them a recipe, usually a dessert. If you want to know how good a communicator someone is, have them write out a recipe and see how well the finished product turns out.

It comes down to this: the majority of manuals and technical writing shouldn’t be geared to a specific, in-the-know audience. Most how-to’s and step-by-steps are meant, by and large, for laymen. Certainly, as many of you can attest, there have been times where you just shake your head trying to get something to work, and when it doesn’t, you feel upset, disappointed and like a failure.

The goal of technical communication is to empower people, not make them feel like idiots.

There are few things worse than believing you aren’t smart enough to make something work properly, even with your college education or years of experience. The goal of technical communication is to empower people, not make them feel like idiots. Sadly, this concept is often lost on those who actually create these things. Instructional manuals of any type are not vetted through proper and thorough testing of the writing, instead believing that the end user has a base set of knowledge that is a given.

A screenshot used in a recent tutorial explaining how to adjust variable bit rate in iTunes, which is not a common practice even though the program itself has been downloaded and used by tens of millions of people.

This may be fine for those manuals and how-to’s where a certain level of technical skill is required. For example, if I am giving a how-to on a Photoshop tutorial where I am asking the end user to save the file as a EPS file and not a JPEG, my assumption is that if they are accessing a how-to on a specific technical program that takes training to use, this should be common knowledge to that user.

“I didn’t know how to do it on my cell phone, so I called my granddaughter, and now I am on the Facebooks.”

Given the example of the many instructional manuals that accompany the myriad electronic devices that have passed through your hands over the years, you know that there is a certain level of frustration on just getting something you paid good money for to work when it doesn’t.

A humorous look at why technical writing geared toward older people who attempt to use new technology is critical that it addresses their knowledge base.

With populations that have not always had these types of devices, say those over 55 years of age, a phone call is typically made to the grandkids. It is something I have heard more than a few times: “I didn’t know how to do it on my cell phone, so I called my granddaughter, and now I am on the Facebooks.”

Some of these posts should come with a warning label: “Do not operate heavy machinery while reading this.”

Recipes are a very unique type of technical writing: As I scanned recipes online before writing this article for comparison, I was shocked, saddened and amazed on critical steps missing in making something as simple as a coconut macaroon. The writer would be admonished by commenters online for leaving out a critical step, like beating the egg whites. And if you needed said eggs, or anything else, there is a convenient shopping list at a store near you that just magically annoyed me and literally got in the way of what I was looking for. 

This, of course, was after having to wade through the author relating some dull stories about the importance of the recipe through flowery prose that almost required me to go to the drug store and get some No-Doze. There was talk of the scenery, the season, etc. What I really needed to view was an ingredients list. Some of these posts should come with a warning label: “Do not operate heavy machinery while reading this.”

If you have no idea what stiff peaks look like on egg whites, you might just give up the process completely.

This has been the tragic result of some types of technical writing: it gets lost in the marketing of it, which dilutes the message and the purpose of why the writing exists in the first place. In creating an “experience” and attempting to sell you as much stuff as possible, why you went to search out this writing can now make you critical of it and even cause you not to seek it out again.

It gets worse from there: if you are new to making your own food, as many young people are, since home economics courses are often usually the victims of budget cuts at the public school level, you might have no idea how to even do what were once considered basic and easy skills to do from people of my generation (Generation X) who learned these things by doing them in classrooms. If you have no idea what stiff peaks look like on egg whites, you might just give up the process completely.

Stiff peaks with egg whites means that you have made a meringue, which is a white, fluffy mixture. Stiff isn’t a word I would use to describe this, but that is the common parlance.

Something that typically isn’t discussed that should be addressed is economics. Technical writing has also taken on a new dimension that is lost on those who are creating how-to’s: the things you write can have a major impact on the end user’s pocketbook. This may include ingredients to a recipe or the ability to afford to buy specific cables for your new camera or laptop. (Those of you who have purchased a Macbook in the last year know exactly what I am talking about.)

I should always offer solutions or workarounds that don’t assume you are made of money.

Think about this way: the cost of food has outpaced the cost of living as wages have stagnated, according to Forbes. Additionally, two of the cities in their list of U.S. locales where the cost of living is surging, especially among non-housing costs, are in the state I live in, Oregon. (I live in the Portland Metro area and can fully attest to this dilemma).

I should always offer solutions or workarounds that don’t assume you are made of money. If not, then I have failed as a technical communicator. In other words, people will settle for less for the sake of convenience.

If you don’t believe me, read this article from the American Institute for Economic Research that details why we are eating unhealthy foods. Cheap food, often filled with things you can’t pronounce and have no idea what they truly are, comprise components in everyday things you buy ready-made in the supermarket. The people who make them have tremendous political power, which directly affects the price of everyday foods we consume. Why spend the time and cost in making it when you can have the ease of just buying it, regardless of the known health risks?

This is an aftermarket attachment I had to purchase for my Macbook Pro last year just to make my older peripherals work with it.

This is also true of the sales of electronics: I prefer my Macbook Pro any day to a PC laptop, but understand that many PC’s are plug-and-play, much easier to use and still compatible with things I already own.

Why do I choose food preparation as an example and metaphor of technical writing? Food is the most common denominator anyone can utilize. We all have to eat; it is simply biology. Cooking is also something of a strange and unusual skill to many young people nowadays. They seem fascinated by cooking and baking shows, but seemingly will never attempt these things themselves, because they way cooking is presented is considered a major and unusually difficult challenge.

This is why I choose cooking as an example of technical writing: it’s personal.

I am amazed by people who create glass objects. Making a glass object is something I may never do, but I still marvel at the process. It does require a certain amount of education only a few possess, lots of practice and specialized, costly equipment. The difference in using cooking as an example of technical writing is that it’s personal. You can do it in the privacy of your own home, it’s a process that requires few specialized tools, it is done everyday by literally billions of people, you can share the end product and you can see quick results.

With these things in mind, here are some quick tips and tricks I use to make my own technical communications easier for the end user, or at least attempt to.

Here are ten things that make technical writing better for the end user:

An example of what mathematics textbooks used to look like, and now you know why old folks complain about their experiences in education so much.
  1. Pictures/Illustrations/Video. We live in an age of visual communication. I marvel at mathematics books now compared to when I went to school: charts, color, etc. that make the process easier to follow than the literally plain text and formula examples I had back in high school. Pretend your end user is from Missouri…
  2. Be clear and concise. It isn’t enough to create step-by-step instructions for end users. If you assume they know something that is “common knowledge” to only a few, then you have failed. For example, I asked you in item #1 to pretend your end user is from Missouri. If you didn’t know that the state motto of Missouri is the “show me state”, then what I have written won’t mean anything.
  3. Layout. In addition to visual pieces like those in item #1, how the entire layout of the finished piece makes a huge impact on the end user’s comprehension. In this blog post, I have used not just images, but pull quotes and color to ease eye strain. There are also no pop-up windows competing for your attention, for example.
  4. Tone. Using a relaxed, conversational tone to general use technical writing creates a sense of ease and trust with the end user. Never talk down to them or assume they know what you know.
  5. Avoid overly technical words and unusual phrases if you can. Much like in item #2, using clear and concise language is only part of the game. I am not saying to dumb-down your message at all, but my throwing around a phrase such as raison dêtre might just confuse someone. Your writing should not fall into the “I’ll take Foreign Words and Phrases for $600, Alex” category as if it were a response on the game show “Jeopardy” if it can be avoided.
  6. Test it, and more than once. Since I like writing about food and technical writing, a little story about one of the masters of both crafts, Julia Child.

    I work for a used bookseller currently in their e-commerce department. A title that never seems to stay on the shelf is Mastering the Art of French Cooking. You can’t throw a cat without hitting at least 100 cookbooks at any given time in my place of business. (I know, that is some kind of visual…)

    Why does this title, published three years before the Beatles even came to America, still do well? It wasn’t just that the primary writer, Julia Child, went to the most prestigious cooking school in the world, the Cordon Bleu. The first volume took SEVEN YEARS to complete, because of testing, revisions, more testing and more revisions.

    Child biographer Noel Riley Fitch stated that “the publication of Mastering the Art of French Cooking instantaneously changed the entire American cookbook industry, leading more cookbook publishers to place emphasis on clarity and precision.” It made cookbooks utilize technical writing as a useful format.
  7. Offer solutions and substitutions when you can. Recently, I assisted someone with dying their hair. (One of my many jobs while in college was as the receptionist at a Perfect Look salon, and yes, I picked up a few things.) This person had used too much dye during the process, and it looked dark, dull and completely muddy. Instead of suggesting that they go purchase an expensive hair color remover and start over, I told them to use dandruff shampoo, leave it in for five minutes, then wash it out. Afterward, I suggested that they make a paste of warm water and baking soda, leave it in until their skin started to tingle, then wash it out. Almost like magic, the color and overall appearance finally looked more natural and less, well, dyed. 
  8. Use real-life examples and be honest. As I have written here, I spoke of real-life examples that relate to my technical communication skills because end users live in the same world you live in, and they are more than likely going to relate to those with the everyday experiences and failures even professionals have.

    In a recent blog post about Adobe Audition audio mastering software, I detailed a solution that isn’t offered by Adobe themselves. This solution, of course, didn’t come without a fair amount of trial and error, and I detailed my experience with the software program to the end use to illustrate that even I, the writer and pro, had difficulty getting from A to B and had tested different outcomes before publishing my findings, much like a scientific paper that uses, you guessed it, technical writing as a format.
  9. If something seems strange, explain why. This is nowhere more evident than with recipes, especially desserts. I heard the following in a video online: “If salt is bitter, why does the cookie recipe call for it?” I could explain, very technically, that Salt is hygroscopic, which means it attracts water...yeah, I have already lost you, violating rule #5 here. I simply explain that salt is an important part of the chemistry of cooking, and without it, your baked goods won’t turn out well. You may not hold a Master’s degree in high level science, but you are familiar with chemistry, and more importantly, you know what crap food tastes like. 
  10. Celebrate victories and encourage feedback. No one, not even technical writers, live in a bubble. There may be something that even a pro may have missed or hasn’t tried. Online posts, such as this, can be an amazing tool for engaging end users and encouraging them to share their experiences that may make your next batch of cookies even better.

    If the feedback appears negative, remember one thing: are you taking this seriously, or are you taking this personally? A good professional knows the difference. 
What you reference in technical writing for the layman should never be as difficult as a “Jeopardy” game show response.

I hope this helps ease the trouble some of you have had in the past with technical writing, why it is important, and what you can do to not just improve your communication, but make it with these goals in mind: useful, empowering and convenient.

And, for those who have been wondering, you can link to my Travis Bear Coconut Macaroon recipe here. Enjoy.

Love to you all.

Ben Brown Jr., owner

Just for fun, here is the one and only Julia Child in a series of moments exemplifying exactly she she wasn’t just a master chef, but a master technical communicator. And yes, she did seem to often have alcohol around a great deal when she cooked. It certainly makes my meal preparation a whole lot more enjoyable.

Julia Child, Master Chef and Master Technical Communicator.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Scroll to top