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.
Simple, direct instructions are hard to achieve. If the interface doesn’t have these characteristics, then its going to be difficult to make the manual match those expectations. Even a simple form has a navigation path to the form, and that path may not be simple.
Microsoft uses a 1:5 ration of writers to programmers. Of course, they are rich, and manuals are just market barriers anyway–nobody reads the manual, ask technical support. Their writers write document specs, not a manual. Then, those specs go to an external contractor, so the real ration is more like 2:5. Trainers write based on the manual and their own more task focused knowledge. By the time the marketers write, the sales trainers write, the trainers write, and the manual writers write, the ratio is probably more like 1:1.
Writing starts before you code. That writing won’t have much to do with the actual code.
If you wait until you have code to hire a writer, you have waited too long. If you don’t know your market, aka your writer’s audience, don’t hire a writer. If the instructions are not simple and clear, fix your interface, particularly the navigation path to the page or form. Why do you need instructions in the first place? If that state diagram sucks, fix the code. It’s not the diagram’s fault, or the writer’s fault, or the artists fault. Fault the code. Fault the plan. Look in the mirror.
In your defense, I will say that some manual writers are fiction writers in diguise who could never write Press OK, and mean it! I will also say that manual writers are trained by their professors that they know nothing, and that they must ask about everything under the sun, rather than experiment and test. Even if your writer can experiment and test, that takes time. When it’s gotta be next month, you might was well sit in their cube, because they don’t have time to experiment and test.
Hire them early enough to get their estimate and dependencies in your estimate and schedule for the next release, as in way back at the beginning. And, no, they can’t finish the day the code is finished.
No, don’t let a programmer write it. Maybe you should write it, ah, but you have other things to do. Oh, well.
[…] 3, 2009 by EC Just read this post on product manuals: <https://effectivus.com/2009/03/the-joy-of-product-manuals/> – thanks to the Productologist for the link: […]
Thanks for the comment David. It is really hard to get this right, especially for smaller technology companies who don’t feel they can afford to employ lots of writers. Face it, they don’t even think they can afford QA, but that is another story!
Do people read manuals, or use the help? I think they do, but I suspect that we do not understand how, when and why they use them, just like we often don’t really understand those issues around the product in the first place.
Me, I’m certainly not a, “let’s start at the very beginning”, but do expect to be able to find the answer when I hit problems.
Just yet another of the very many things that are hard to get right in NPD.