Skip to main content
shopping_basket Basket 0
Log in

The art of writing user manuals


Have you lately visited a public toilet, and these three buttons invited you to judge your experience?

UX (User Experience) has been recognized as one of the most critical factors for making a product successful. But many engineers think UX is primarily about the usability of a UI (user interface) and therefore limited to designers of frontends like websites or dashboards. This is just a tiny part of it. UX spans over the whole life cycle of a product. Including advertisement, sales, and manuals – including product evaluation. Sad enough that the lion’s share of user documentation and evaluation material is written by engineers with no or little knowledge of didactics and psychology. As a user, I would love engineers to improve the "evaluation ability" of their products. If you kill my interest and let me have no or hard success during the evaluation process, you have delivered a show stopper: I will never get further UX with your product!


Common problems with evaluation kits and user documentation

In my over 40 years of reading technical literature and trying to learn to handle new electronic products, I have seen excellent as well as unacceptable user manuals. And I'm not talking about the automatic translation of Chinese material. I'm talking about engineers writing in their mother language but being unable to think from the perspective of an inexperienced "muggle". 


“You burry me in thousands of pages manuals!”

I get your evaluation board and links to PDF files, which reference to application notes which reference to datasheets which reference to manuals which... It would take weeks to read and understand all that material. Without even knowing what I will get from this effort, I desperately give up right in the beginning.

“Help! I will never be able to make this! I can’t even see the top of the mountain!”

Best case for you: I use google to lift me up to your level of wisdom hopefully :


“I need a shortcut! Let’s try google… praying for reliable information!”

Some of your colleagues are very smart. They break the stuff into smaller portions and try to lure me verbally: “Just a few pages, and you’re done”. The full truth is, after a few pages, I’m done with step 1 of the evaluation project – still not knowing how many steps will follow and what my reward will be. This smart trick fails when I've mastered three steps and get the impression that they badly fooled me.

Maybe you’ll get away with this trick if I turn back and think:


“Oh no! I must go on with his torture or I would have wasted all the time I’ve invested until now!”

Okay. You’ve got it. You reduced the number of pages to a minimum and provided an evaluation board. You explained the excellent result I will experience if I invest a few hours to work through the quick start manual. So I made my way up the steps and got to the top of the mountain. I can already see and smell my award. But alas: I overlooked the ambuscade and directly stepped into the pitfall: I should have removed some of these small jumpers before switching on that thing!

To be honest: when re-reading the few pages manual, I must confess that you have warned me. But your warning was hidden in some gibberish technical terms I was not able to understand at that point. Too bad! Now I cannot even blame you:


“Couldn’t you just mention that there is a trap door on top of the mountain?” (use your browser's zoom;-)

I could go on by mentioning missing links in manuals, outdated instructions which got obsolete with the newer tool's version I have just downloaded, multiple technical terms for the same thing, or omitted details which proof my simple mind compared to the author’s great wisdom. But I fear most of you readers do have made similar experiences, and I might not tell any news. So I better proceed by sharing some constructive ideas.

Some thoughts you might consider

  • Don’t expect too much knowledge or experience from your users.
  • People are curious – so are the users! Try using their curiosity.
  • Everyone loves awards. Success is a powerful award. Try making success as easy as possible for the users.
  • Try to avoid flat learning curves – especially without intermediate moments of success.
  • Do split complicated and complex topics into easy to master portions, each ending with success-award.
  • Don’t be an instructing teacher! Think and write like a user among users.
  • Double proof your links and ensure that they will be online for the full lifetime of your documents
  • Do not use third parties’ (or colleagues’) material without testing their instructions yourself.
  • Do test every instruction with products out of the shelf. Do not use any fancy R&D versions of the products.
  • Keep in mind that not only software might change with versions. There MUST be obsolescence management for the documentation. A warning to keep it the documentation up-to-date should automatically pop up whenever hard- or software has changed. Do not expect the users to coordinate things by reading any change-log documents.
  • Each evaluation kit MUST be bundled with a unique (short!) link to the up-to-date software belonging to this hardware version.
  • Do not agonise the users with QR codes printed on the eval-kits for documentation links! Would you use a smartphone to read PDF documents? Do use permanent short links instead (ask your IT department to set up such domains).
  • Do use 1 unique technical term for 1 thing (tool, part, product, button, tab, document, file). Users don't want to guess if 2 terms mean the same thing.

At the end of the day, YOU are a user too! So try stepping back and look into your documents or eval-kits like any other user would do. If you find this hard to do, then go and find a colleague who is not involved in the product and who is willing to test things like any other user would do.

Please use the comment section of this article to share your proposals for better UX of manuals and eval-kits.

Volker de Haas started electronics and computing with a KIM1 and machine language in the 70s. Then FORTRAN, PASCAL, BASIC, C, MUMPS. Developed complex digital circuits and analogue electronics for neuroscience labs (and his MD grade). Later: database engineering, C++, C#, industrial hard- and software developer (transport, automotive, automation). Designed and constructed the open-source PLC / IPC "Revolution Pi". Now offering advanced development and exceptional exhibits.


October 21, 2019 10:13

Thanks a lot. This list will be my reminder for my next contents.
And I'll add a simple glossary for me and my users to keep 1 unique technical term for every 1 thing (tool, part, product, button, tab, document, file).

0 Votes

October 21, 2019 10:12

I wish there was a course I could follow. I have to write manuals and I just don't get it right. I fall into all the pitfalls you mention. Been trying for 15 years now.

0 Votes

October 15, 2019 07:31

I really in joyed reading your article. An got a lot out of it. Going to start a project this week on a way of new power. I will have to read a lot on this site I can see to build this.
10 Oct. 2019 10:07 PM

0 Votes

October 15, 2019 14:55

thnx @makeitwork !
And good luck with your new project!

DesignSpark Electrical Logolinkedin