Your Instructions Are Bad, But Don't Feel Bad
It’s not your fault.
Life (and the internet in particular) has conditioned you to write terrible instructions – Instructions which are ambiguous, rambling, incomplete, or insufficiently informative. So how can you fix them?
The most important thing you can do as a successful artist – especially as a writer – is to remember that your creation exists for your audience to consume. This is not to say that there’s anything wrong with creating selfishly: you can make art only to gratify you, the creator; or to experiment. However, if you create selfishly, and then expect the masses to laud your artistry, you’re almost certainly doing it wrong. In rare cases you might get lucky (or maybe you’re the next Mozart and you excrete masterpieces), but if you set out to be a selfish writer, chances are you’ll fail.
There’s no point in writing an English novel if your audience only speaks French. Your article on the Challenger disaster will fall flat if you use a plethora of rocketry and engineering terminology on an readership of laypersons. And, though it baffles the mind that it even bears saying, instructions fail when the writer fails to – you know – actually instruct.
Instructions aren’t exactly high art, but the consideration for one’s audience, their background, and their motivations for reading is paramount. For those looking to become better instructional writers, here’s some common examples of instructions on the internet, good, bad, and ugly (or just skip to the instructions on how to do it right).
THE BAD: Narcissistic Recipes
The worst offenders of the bunch, Narcissistic Recipes are central to the matter of bad instructions on the internet. It’s likely everyone who loves to make food has encountered a Narcissistic Recipe at least once during their internet travels. The scenario is thus: you want to cook something, bake something, or mix a drink, so you type that thing into Google. If you research food and drink prep the way I do, you read laterally and open a few different recipes in different tabs to get a sense of what the commonly-accepted procedure is (and to avoid being taken in by a recipe written by someone who doesn’t know what they’re doing).
Your first search result is a posting on a blog. You start reading, and it goes something like this:
When I was a little girl, I was always excited by late winter and the arrival of seville orange season. My nonna would come home from the market, basket brimming with these lumpy, fragrant delights. Part of my essential Italian heritage comes from blah blah blah…
You begin to realize that the instructions won’t actually begin anytime soon, so you start scrolling down. You make your way halfway down the page and start to read the content, but the instructions still haven’t begun yet. At this point you want to reach into your computer screen and haul this yuppie, basic, self-absorbed Martha-Stewart-wannabe through the internet and into your kitchen so you can tell them to shut up and explain how to make marmalade already.
The reason you are so irrationally angry is because you (the reader) set out to understand how to make marmalade (your motivation for reading), and the blogger (the author) has selfishly decided that you need to know their entire origin story as a human being in order to do that. This is why blogs can be both an amazing and infuriatingly bad source of recipes: it all depends on how much navel-gazing the blogger wants to do.
One Simple Fix
If you post a recipe on your blog, chances are that people who land on that page from Google are looking to make the recipe – and quite frankly, they don’t give a crap about your nonna’s love for oranges (sorry nonna). You can help your reader achieve their goal (of making the damn recipe) by adding a link to skip to the instructions early on. Or better yet, put the recipe at the start of the entry before you wax nostalgic.
THE UGLY: Uninstructive Instructables
I love Instructables. The site (whose slogan is “Make Anything”) has been around since 2005 and is still going strong. The great thing about Instructables is that anyone can make one. The terrible thing about Instructables is that anyone can make one.
Instructables can suffer from a lot of different problems. They too can be Narcissistic Recipes – droning on about the author’s backstory, likes, and dislikes. They’re frequently rife with spelling and grammar mistakes. More critically, they often have terrible structure. As with any writing, a good editor would help a great deal, though in this case that seems unlikely.
I have recently written an Instructable which constitutes a bad set of instructions. Why? The problem is that Instructables – primarily a site where makers showcase their creations – isn’t really geared towards providing great instructions. So is Instructables bad? I wouldn’t say so: an Instructable can still be viewed as a useful genre of structured writing called a process description.
Process descriptions describe how something happened or how it was done, but unlike instructions, their goal isn’t necessarily to instruct the reader on how to duplicate the result. In the case of Instructables, a maker might have had access to materials, tools, and skills that the reader does not. However, by providing a detailed description of how they made something, a maker can both showcase their creation and relay information which might allow someone else (with an appropriate skill level) to create something similar.
The Somewhat Complicated Fix(es)
If you want your Instructable to be useful – either as instructions or a process description – there’s a few things you need to do. Break down long, complicated steps into smaller sub-tasks when possible. Avoid superfluous information (such as backstories or anecdotes). If you almost messed up or encountered a problem that you think others might encounter, you can include a note or WARNING highlighted in some way, so that others can avoid the same pitfall. Lastly, take advantage of Instructables’ ability to add mouseover notations to images – this can enhance the very-important visual element of your Instructable.
At the end of the day though, Instructables can be entertaining to read – so perhaps that’s the site’s primary goal?
THE GOOD: iFixit Guides
Pointing out flaws isn’t a complete argument – one needs to provide an example of something done well. When it comes to well-done instructions, iFixit is the gold standard: the “how-to” of how-to guides.
For those who don’t know, iFixit is a site that provides tear-down, repair, and upgrade guides for products that discourage doing such things – particularly Apple devices. As with third-party software and peripherals designed for macOS, Apple’s minimalist and human-usable design bleeds over into iFixit (somewhat ironically). It’s clear that iFixit either has some technical writers on staff, or they’re just really, REALLY excellently self-taught.
Why iFixit Guides Are So Awesome
iFixit’s official guides check almost all of the boxes for good instructions and technical writing (their community-submitted guides can be a bit more hit-and-miss). Let’s go over some of those good attributes.
Chunking – iFixit understands the importance of “chunking” content; that is, breaking it down into appropriately-sized groupings. Any procedure is logically broken up into consecutive steps, and each step is composed of individual consecutive tasks. Chunking also allows your reader to skip over any steps that they might already be familiar with, or that aren’t relevant to them.
One Action Verb – One of the most important things you can do when writing instructions is to base the main clause of every step or task around a single imperative verb; the action the user is meant to do next (eg: “Open the case” or “Remove the five screws”). Conditionals and modifiers are allowed (eg: “Before proceeding, unplug the power” or “Carefully turn the dial”). It’s usually best to use only one action verb per step, unless the actions must be performed more-or-less simultaneously.
Excellent Visuals – Every step has at least one image showing the component to be manipulated in the current step. Some steps have multiple images which indicate motion or change, a great way of showing cause and effect to the reader. Other images have coloured circles to indicate multiple locations of different-but-simillar components (typically screws with different sizes or heads). Such visuals allow you to show the user how to do something or how something happens in a way that might otherwise be arduous and/or tedious to explain with text.
Flags – Flags tell your user some critical piece of information that may or may not be immediately relevant to the step at hand. iFixit guides make good use of notes and warnings by including an icon and red or grey text to alert the reader. Flags are especially important if the step has the potential to cause damage to the device or even harm the user.
Great Metadata – Every one of iFixit’s guides begin with a block of easily-readable metadata. There are lists of which parts and tools are required for the task at hand, with applicable links to purchase them if necessary. The guide also tells you the overall difficulty (compared with other iFixit guides), the estimated time to complete the procedure, and the length of the procedure.
Conclusion
Not everyone can (or should) be a technical writer, but the fundamentals of writing instructions are simple enough that everyone who writes them regularly should endeavour to learn how. But, did I break my own rules with this article? This post isn’t the best instructional design, is it? Perhaps, but my primary goal here isn’t to educate technical writers and instructional designers – this article is less instructional and more rhetorical. I hope this piece underscores the value of well-written instructions, and maybe as a bonus it will help new writers avoid some of the pitfalls.
And maybe – just maybe – I’ll get to read one less recipe that begins with a novella about some lady’s relationship with her grandma.
Image credits:
mandarins & components via Pixabay
MacBook NVMe replacement via iFixit