The Joy of Product Manuals

Even when the product first makes it into the market the manual might not appear too important.  After all those eager Early Adopters just love tinkering with the product to figure out what it does and how and why.  If you wrote a manual they would probably use it as a door stop.

Then your product gains some traction and starts to sell into the wider market.  Suddenly your support engineers are tearing their hair out, the phones are melting and your customers are complaining and all because they don’t know how to use the product.

Quick, quick, we must have a product manual!  You go to a professional and are surprised and disheartened to learn that they expect to make a living wage and would take 9 months to write a half decent manual.  Plus they have all sorts of irritating questions for you about your target market, the types of users, their levels of technical knowledge, understanding of industry standards, etc, etc.  Which all make you uncomfortable enough to delay doing anything.

Eventually some brave soul steps forward; “Well I guess anything would be better than nothing” they say.  It could be someone from Support, Quality Assurance, Engineering, Marketing, Product Management, Training, or a Product Specialist. I’ve literally seen them all.

So this poor unfortunate soul sets about trying to complete a very complex and difficult task in “a few weeks”.  Outcomes vary;

  • “Press the Save button to save the project” – I’d never have guessed that.
  • “See the appendix for details of the file format”, “Appendix: File Formats, TBD”, Truly, Badly, Deeply?
  • “Always keep the Ribbon minimized” – why, I thought we tied it to the tree?
  • “Selecting the Field Dominance button switches the field dominance” – images of dominatrix bisexual rabbits come to mind, but not a lot else.
  • And the classic oxymoron: “This page intentionally blank” – as was my understanding, and it remains so.

The trouble is, it’s complicated.  One reason it is so complicated is that the manual has to fulfil several very different needs;

  • The first time user thinking “oh my God, what button do I press?” needs a Quick Start Guide.
  • The occasional user recalls “every damn month I have to do this and I can never remember which way round the parameters have to go” needs a How To Guide.
  • The support engineer “I just need to find the wiring diagram for the interface cable” wants a Technical Reference Guide.
  • Etc, etc…

I’m no expert technical author, but I’ve had these conversations with those experts enough times to know how difficult it can be to decide just what information to present, in what form and to what target audience.

What is less complicated is that when we do write a product manual, it should be clear, it should be free of jargon, and our use of English should be simple and direct.  We can structure our documents clearly and sensibly (no, don’t start with the file menu just because it is on the left), and we can help our readers find the information they want (it is called an index).  And it is not just about our product manuals, but all of our communications from our website to our business cards.  That’s what Design for Clarity is all about, and why we could all do with a dose of it.