feature article
Subscribe Now

How to Write a Manual


“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 29, 2023
Cavitation poses a formidable challenge to modern boat design, especially for high-speed sailing vessels participating in events like America's Cup , Vendee Globe , and Route du Rhum . Hydrofoils, in particular, are susceptible to cavitation, which can cause surface dama...
Nov 27, 2023
Qualcomm Technologies' SVP, Durga Malladi, talks about the current benefits, challenges, use cases and regulations surrounding artificial intelligence and how AI will evolve in the near future....
Nov 27, 2023
See how we're harnessing generative AI throughout our suite of EDA tools with Synopsys.AI Copilot, the world's first GenAI capability for chip design.The post Meet Synopsys.ai Copilot, Industry's First GenAI Capability for Chip Design appeared first on Chip Design....
Nov 6, 2023
Suffice it to say that everyone and everything in these images was shot in-camera underwater, and that the results truly are haunting....

featured video

TDK CLT32 power inductors for ADAS and AD power management

Sponsored by TDK

Review the top 3 FAQs (Frequently Asked Questions) regarding TDK’s CLT32 power inductors. Learn why these tiny power inductors address the most demanding reliability challenges of ADAS and AD power management.

Click here for more information

featured webinar

Rapid Learning: Purpose-Built MCU Software Tools for Data-Driven Embedded IoT Systems

Sponsored by ITTIA

Are you developing an MCU application that captures data of all kinds (metrics, events, logs, traces, etc.)? Are you ready to reduce the difficulties and complications involved in developing an event- and data-centric embedded system? This webinar will quickly introduce you to excellent MCU-specific software options for developing your next-generation data-driven IoT systems. You will also learn how to recognize and overcome data management obstacles. Register today as seats are limited!

Register Now!

featured chalk talk

High-Voltage Isolation for Robust and Reliable System Operation
In this episode of Chalk Talk, Amelia Dalton and Luke Trowbridge from Texas Instruments examine the benefits of isolation in high voltage systems. They also explore the benefits of TI’s integrated transformer technology and how TI’s high voltage isolations can help you streamline your design process, reduce your bill of materials, and ensure reliable and robust system operation.
Apr 27, 2023