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
Oct 27, 2020
As we continue this blog series, we'€™re going to keep looking at System Design and Verification Online Training courses. In Part 1 , we went over Verilog language and application, Xcelium simulator,... [[ Click on the title to access the full blog on the Cadence Community...
Oct 27, 2020
Back in January 2020, we rolled out a new experience for component data for our discrete wire products. This update has been very well received. In that blog post, we promised some version 2 updates that would better organize the new data. With this post, we’re happy to...
Oct 26, 2020
Do you have a gadget or gizmo that uses sensors in an ingenious or frivolous way? If so, claim your 15 minutes of fame at the virtual Sensors Innovation Fall Week event....
Oct 23, 2020
[From the last episode: We noted that some inventions, like in-memory compute, aren'€™t intuitive, being driven instead by the math.] We have one more addition to add to our in-memory compute system. Remember that, when we use a regular memory, what goes in is an address '...

featured video

Demo: Inuitive NU4000 SoC with ARC EV Processor Running SLAM and CNN

Sponsored by Synopsys

Autonomous vehicles, robotics, augmented and virtual reality all require simultaneous localization and mapping (SLAM) to build a map of the surroundings. Combining SLAM with a neural network engine adds intelligence, allowing the system to identify objects and make decisions. In this demo, Synopsys ARC EV processor’s vision engine (VPU) accelerates KudanSLAM algorithms by up to 40% while running object detection on its CNN engine.

Click here for more information about DesignWare ARC EV Processors for Embedded Vision

featured paper

Overcoming PPA and Productivity Challenges of New Age ICs with Mixed Placement Innovation

Sponsored by Cadence Design Systems

With the increase in the number of on-chip storage elements, it has become extremely time consuming to come up with an optimized floorplan using manual methods, directly impacting tapeout schedules and power, performance, and area (PPA). In this white paper, learn how a breakthrough technology addresses design productivity along with design quality improvements for macro-dominated designs. Download white paper.

Click here to download the whitepaper

Featured Chalk Talk

General Port Protection

Sponsored by Mouser Electronics and Littelfuse

In today’s complex designs, port protection can be a challenge. High-speed data, low-speed data, and power ports need protection from ESD, power faults, and more. In this episode of Chalk Talk, Amelia Dalton chats with Todd Phillips from Littelfuse about port protection for your next system design.

Click here for more information about port protection from Littelfuse.