feature article
Subscribe to EE Journal Daily Newsletter
8 + 9 =

How to Write a Manual

When RTFM Meets PEBKAC

“Save the Manuals!” – Car and Driver

 

I’ve got one word for you: #NaNoWriMo.

That’s the hashtag for National Novel-Writing Month, a lighthearted and voluntary effort to get budding writers to buckle down and start on that book. Your novel must be at least 50,000 words long (about 200 pages) and you’ve got to finish it by the end of November. Consider it a nudge to encourage your inner Faulkner, Rowling, or Pynchon. Nothing motivates like a deadline.

But if fiction isn’t your style, consider this an elbow in the ribs to start writing better user manuals for your customers.

They say no job is finished until the paperwork is done, and the (often virtual) paper instruction manual that goes with every product we design is usually the last thing that gets done. Now that we’re halfway through November, it’s past time to get started on that great manual you’ve been postponing. To make up for lost time, I’ve provided a handy checklist to help make things easier.

  • Use Lots of Jargon. Nothing impresses your customers like made-up words to remind them that they don’t work at your company and they haven’t been attending internal meetings for 30 months. Phrases like, “Acme’s patented EverClog technology leverages our PDFC and TruWoof-XL lines, and includes our QDP v2, CDDI, and SnotFree VQRDs, as part of the Acme PRO F-class line of KFZs,” really help to show that you’ve developed technology so new that it doesn’t even have words to describe it. Plain English is so last century.
  • The Use of Passive Voice is Encouraged. Nobody wants to read manuals anyway, so why not put your readers to sleep? A favor will be done for them. The jazzing up of text is to be discouraged. Informing is laudable, and thus the information must be in its driest form presented. German grammar could be studied in order for copious examples to be gleaned. Follow this, you must.
  • Everything Is Intuitive. Nothing makes users feel better than being told that their new and unfamiliar purchase is completely intuitive. That makes them feel valued, intelligent, and ready to take on the challenge of mastering your exotic new device. Who needs instructions? It’s intuitive!  
  • Describe the Obvious. Show you really understand your product by writing helpful descriptions such as, “The File menu is for file operations; the Accept button accepts your response; the Options menu brings up a list of options.” Assume that people can’t read the labels on your GUI, and repeat those same labels in your documentation. Better yet, list them in alphabetical order for easy reference. That should do it.
  • Make the manual unprintable. You’ll be updating your documentation constantly, usually right after each customer purchase, so what’s the point of letting them print an outdated version? You’ll keep your users up-to-date and save the planet at the same time. Nobody wants a printout when they can download 100-page updates to their phone.
  • Information Wants to Be Free. It’s a good idea to scatter relevant information all over your website, product manuals, distribution CD, and stapled copies of release notes. That way, users know you’re trying hard. Why else would you spend so much time salting away information in different places? It’s mixed media!
  • Repetition Is Good. If a feature is worth describing, it’s worth describing several times, preferably once per page. (Users have short attention spans.) Why do you think word processors have cut-and-paste features?
  • Protect Your Property. Everyone knows rival firms are out to reverse-engineer your product. Protect your company’s IP (and your job) by leaving important details out of your documentation. The bad guys may be able to buy your product, but they’ll never be able to use it! Don’t forget to leave off any mention of your latest or most important features. You really don’t want anyone to know about those.  
  • Assume It’s Too Late. There’s no point writing instructional material that walks your customer through the initial setup and use of your product. They probably won’t read it until they’ve used the product for several weeks anyway. By that time, they already know how everything works. So just summarize a few points, assuming readers already know the basics. Don’t waste time on redundant tutorials.
  • Translate Badly. Funny translations are a source of mirth around any office. Be sure to hire inexperienced translators who can inject some levity into your overseas customers’ lives. “Hey, didn’t Frank in Sales spend a week in the Philippines once? Let’s get him to do the Tagalog translation!”
  • Weed Out the Weak. It’s a good idea to throw a few “gotchas” into your documentation to make sure users are awake. If they trip up on the obvious mistakes, like when you say to left-click on something instead of right-click, then how can you trust them to get the complicated stuff right? You don’t want your Tech Support staff wasting time on users who can’t figure out the basics on their own.
  • Don’t Get Creative. Use short, declarative sentences. Shun narrative. Eschew instructions. Cleave to facts. Avoid use cases. Intelligible descriptions have no place in instructional literature. Leave the evocative prose to the creative-writing classes at the adult school.
  • Make It Software’s Problem. Honestly, a product this intuitive shouldn’t need a manual at all, am I right? New products are like jokes: if you have to explain it, it’s no good.
  • Make It the User’s Problem. Take a page from the old saying – “If you have to ask the price, you can’t afford it.” If users need to read a manual, they’re probably too dumb to use your product in the first place. I mean, really – who buys a home/office router without first studying the 7-layer OSI model, encryption algorithms, password generation, dipole antennas, MU-MIMO, QoS, 802.11ac, 4G LTE, PoE, VADSL, IPsec, 4×4, and Pringles cans? Caveat emptor, I say.
  • Crowdsource It. You can rely on the wisdom of crowds to produce excellent documentation, while saving yourself a lot of work. Instead of wasting your day writing stuff nobody will read, start an online support forum and let the customers help each other. They’re probably better at finding workarounds, patches, and fixes anyway. And – bonus! – they speak lots of different languages, so you don’t have to translate anything. Once you get 1000 or so users swapping constructive criticism with each other, you can sit back and let the manuals write themselves. Give yourself a bonus for ingenuity.
  • Don’t Rush Things. Software updates are such a drag. Every time the firmware guys add a new feature or fix a bug, you need to update the documentation. How will you ever keep up? Better to let the updates accumulate and only publish manual updates every ten revisions or so. The software changes probably aren’t a big deal anyway. Nobody will notice if the features and the documentation don’t match.  

The real solution, of course, is to design products so obvious, so intuitive, that they don’t need instruction manuals at all. True elegance lies in minimalism. Reduce superfluous documentation and let the product’s sophistication shine through. Your customers will thank you for it every time they call Tech Support or visit your online forum. Take the rest of the month off.  You’ve earned it.

3 thoughts on “How to Write a Manual”

  1. I hate to tell you this but you have missed the boat. The above suggestions have been in place as an industry standard for a very long time.

    You did forget to put the point in: Assume all users already understand what the main use cases are for the software. Never tell them what problems it was developed to solve. If they do not know that they should have never opened the software in the first place.

  2. I disagree on “Assume It’s Too Late” Instead spend the first two/three chapters on minute detail on how to set things up (in the old days this would include a large chunk on how to put a floppy disk in to the computer and then how to take it out) Spend enough time and paper on this and you won’t have space for other things.

  3. Nice start, but you forgot to important steps.

    (1) Create a Youtube channel to explain your product. If you don’t do this, your competitor will. Besides, how many times have your heard, when bragging about finishing the Complete Works of Dostoyevsky, “I will wait for the movie.”

    (2) Leave a product review of your competitor’s product. You are going to buy one, anyway (aren’t you ??). Be sure to point out how non-intuitive their product is, and how worthless the manual. If you are feeling mean, say the software is buggy.

Leave a Reply

featured blogs
Nov 17, 2017
CASPA is the Chinese American Semiconductor Professional Association. Once a year they have their annual conference and dinner banquet. I ended up getting involved with them a few years ago when I stepped in with 24-hours' notice to moderate a panel session for them, plu...
Nov 15, 2017
SuperComputing 2017 remains in full force this week from the Colorado Convention Center in Denver.  There are lots of activity in presentations, seminars, demonstrations and exhibits on the tradeshow floor. Stay tuned to the Samtec blog the rest of the week for more highligh...
Nov 16, 2017
“Mommy, Daddy … Why is the sky blue?” As you scramble for an answer that lies somewhere between a discussion of refraction in gasses and “Oh, look—a doggie!” you already know the response to whatever you say will be a horrifyingly sincere “B...
Nov 07, 2017
Given that the industry is beginning to reach the limits of what can physically and economically be achieved through further shrinkage of process geometries, reducing feature size and increasing transistor counts is no longer achieving the same result it once did. Instead the...