Thanks to the EU, tech companies must now provide repair manuals for their products. But there’s a huge gap between creating a manual, and creating a good manual. Some companies (we’re looking at you, Mackie) elevate the manual to a joyful art form that’s as entertaining as it is useful. Others excrete the minimal possible documentation with such resentment that it feels like they hate the user.
Today we’re going to look at what makes a good user manual, and look at some examples of some of the worst manuals we have seen. And because sniping at bad actors is so much fun, let’s start there.
A YouTube Video Doesn’t Count as a Real Manual
Last week, I wanted to know the correct dose and dilution of my lemon-tree fertilizer. The bottle is covered with all kinds of text, but after a solid minute of turning it around and around, trying to read the tiny type, I didn’t find any instructions. There was only a QR.
Already annoyed, I scanned it, and the link took me to YouTube. Yes, I had to watch a video to learn how much water to add to a capful of liquid fertilizer. By now, I’m getting angry. The video is 40 seconds long, has no speech (just plinky worthy music), and for the first half is nothing but marketing. I am, it tells me (via on-screen text) “saving the planet.” Presumably the person who wrote that forgot about me needing a smartphone, a data connection, and the YouTube server farm to see the manual, rather than just reading it off the bottle.
23 seconds into , I finally got the text I needed: 30 ml for 5 liters. Text, in a video, linked via a QR code that takes up more space on the label than the final instructions. I will not be buying this brand again.
It’s not that YouTube has no place in repair and instruction. Far from it. Often a focussed video is much faster to understand than even the best-written manual. On the iFixit YouTube channel, we show off everything from how to use a multimeter to how to replace the battery on an iPhone 15 Pro. There’s no reason manufacturers shouldn’t use video to show off how to repair their products: Baratza, the coffee grinder people, make some excellent videos that show clearly and concisely how to carry out basic repair and maintenance, with no fluff at the beginning, or “like-and-subscribe” begging.
But videos shouldn’t replace quick-use labels like the dosage for my fertilizer, and they shouldn’t replace a proper user manual, either. PDF or paper manuals are way easier to browse. You can search, highlight, read the index and the table-of-contents to find info, even if you don’t know what exactly you’re looking for. With a video, you pretty much have to watch it from start to finish or you might miss something. If the video’s creator has added proper chapter markers, that can help, but text and pictures are still the best for quickly jumping around and finding what you need.
Making a proper printed or PDF manual isn’t easy. It takes work and skill, and a real understanding of both the product you’re writing about, and also how the future owner might expect to use it.
So, just how do you write a good manual?
Manual Writing 101
First up, you have to know what you’re talking about. This is the same as writing an article like this one. If I already know a lot about a subject, I can bang out 1,000 words in no time, planning it as I go. If I don’t, the only way to avoid pain for both me and the reader is to research everything first. That often means interviewing somebody who does know the subject. Reading up is ok, but actually talking to the designers is much better, as they can also convey context, saving the writer a lot of time spent just getting a basic idea of the subject. The manual writer’s job, then, is to gather that knowledge, and explain it in a way that’s easy to understand.
I mentioned Mackie above, a company that makes mixers, speakers, and other music-studio and live-music gear. Mackie’s manuals contain anecdotes, and explain not only the raw features, but give examples of how they might be used. The writing style is also easy and friendly, without being annoying. It’s pretty clear that their manual writers know their stuff, both in a general sense, and in a product-specific sense.
As a counter-example, let’s look at Teenage Engineering, a Swedish design company that has made some iconic electronic musical instruments. The manual for its OP-XY portable synth/sampler is pretty much a checklist of what not to do—it launched as web-only, and the PDF version lacks clickable links. At launch, some of the sections were flat-out incorrect, and even now, long after launch, much core functionality is either missing from the manual (full MIDI implementation) or so badly explained that you are left more confused than before you read it. Oh, and the text is tiny, and white-on-black. It’s especially annoying because Teenage Engineering puts so much thought and effort into its actual products, for instance designing a production line just to build a sampler out of commodity parts.
Ideally, then, the manual writer is a technical writer who’s good at explaining, and understands the product. The next best thing is that this good writer works closely with the engineers to get things right.
Short and Sweet
Another essential quality of a manual is to make it concise. Short, but not too short. Mackie’s manuals win here again. You can read the whole manual for a mixing desk in one sitting, maybe drinking a single cup of coffee, but when you’re done, you don’t feel like anything has been missed. I’m always a little in awe of this aspect of their manuals. It’s like they’ve got some kind of TARDIS business going on there.
Part of being concise is being clear. Clarity means no fluff, no digressions, and a minimum of ten-dollar words when one-dollar words will do. A convoluted, confused sentence is often the result of a writer not understanding the subject. To explain something clearly and concisely, you need to know exactly how it works. If you spot fancy language and run-on sentences, beware: the writer is trying to cloak their ignorance in fluff.
We should also mention jargon. At its best, jargon is a very efficient shorthand between peers. But often it just confuses and excludes. Use commonly-known jargon, and lay off the rest. If you’re going to be using a term a lot, though, define it up front, and use the shorthand version throughout.
The best way to test that your manual is pitching this balance correctly? Give it to a novice to read, and also give it to an expert. If the novice understands it, and the expert doesn’t find anything wrong, you’re on the right path.
Entertainment Value
Just because it’s packed full of facts and instructions, a manual doesn’t have to be dry. In fact, I’d argue that it shouldn’t be. A good manual writer, like any good writer, uses anecdotes, real-world examples, and a dash of humor to better convey their points. In our iFixit tech writing handbook for writing a repair manual (yes, we have guides for everything), we have a whole chapter on writing style, and unsurprisingly, it’s packed with examples from Mackie’s manuals.
Here’s one of my favorites. It explains Mackie’s unique and beloved ALT 3+4 bus, which re-routes any muted mixer channel to somewhere more useful.
The dual-purpose mute/alt 3-4 switch is a Mackie signature. When Greg was designing our first product, he had to include a mute switch for each channel. Mute switches do just what they sound like they do. They turn off the signal by “routing” it into oblivion. “Gee, what a waste,” he reasoned. “Why not have the mute button route the signal somewhere useful, like a separate stereo bus?”
So mute/alt 3-4 really serves two functions—muting (often used during mixdown or live shows), and signal routing (for multitrack and live work) where it acts as an extra stereo bus.
Told you those manuals were good.
Who’s it for?
A good manual writer knows their audience. As with jargon, above, you need to judge the level of knowledge your typical reader will have. Someone buying a battery bank for their phone, or a new TV, might have zero technical knowledge, or they may be a total tech nerd. You’ll have to explain things for the lowest level of knowledge, while still letting the expert skim to get to the in-depth info they want.
Folks buying highly specialized gear, like a studio mixing desk, will likely have at least some understanding of the subject, and you can write accordingly. This doesn’t mean you should stuff the text with acronyms. Nor is this an excuse for convoluted sentences that read like the blurb on art-gallery walls. Keep it simple, but know who you’re writing for.
Picture Perfect
Pictures can be essential. They should not replace well-written instructions, but they can make explanations much easier to follow. Photographs can be helpful, especially for repair guides, but there are situations where diagrams are clearer, and focus on the exact point you want to convey. Ideally, the illustrator and the writer should work together.
Ikea’s assembly pamphlets are an extreme example of picture-only manuals, probably used because they don’t require any translation. But once you get used to how they work, IKEA’s manuals are great. If you disagree, I have the manual from a bed-frame I bought from Amazon that I want to show you.
Video manuals can make a great supplement to a written manual, but they should never be the only manual. They’re good for showing exactly how to rotate a part, say, or for identifying and diagnosing mystery noises.
Seeing how much effort somebody puts into a wrench when undoing a bike pedal can make you more confident that you’re not yanking too hard. And for something like making mayonnaise, a video can be way better than words or pictures for assessing speed of pour, and sauce texture.
If you do use a video, make it just as concise as your text. No verbose introductions, no promotions for other products, no lengthy title sequences. Just the instructions. And chapter markers for anything in depth.
What you definitely should not do, is to put a QR code on the side of your bottle, and make somebody sit through an entire YouTube video just to read the text you could have printed in place of that QR code.
Easy to Find
Finally, your manual should be easy to find. If it’s on your website, it should be both in the support/download section, and linked from the product page. Lots of folks will read a manual prior to making a purchase decision.
And while a searchable PDF is good, an online manual has advantages. One, it’s searchable and usable on a phone (PDFs can be awkward on small screens), and two, if you make separate web pages for different manual sections, those pages will show up in search engines, so people looking for answers will be taken straight to the correct page of the manual.
Roland, another music-gear maker, does a pretty good job of its manuals in this regard. They’re available as both PDFs and as HTML pages with copious internal linking. You can also switch between languages on the fly. That’s how our own guides work as well!
I’m starting to love my ridiculous bottle of lemon-tree fertilizer, because it really is the perfect example of how not to do pretty much everything. If you wanted an example of a product that follows absolutely none of our guidelines, there it is.
0 Comments