Saturday, September 13, 2008

The missing span - why user documentation often fails

This week I attended a Technology Association of Georgia Product Management SIG meeting this week. John Mansour of ZigZag Marketing did a presentation about using documented requirements through all phases of the product development cycle. John is a product management expert, and his company has a comprehensive framework for analyzing market needs and responding with well-considered technology solutions.

One of the requirements phases in the framework is the User Phase, which, John noted, is often given inadequate coverage or even skipped entirely. In this stage you create user stories and extend them into detailed "what if" scenarios. All of these must be documented and validated in order to design usable interactions. The analysis yields detailed and tested Functional Specifications that can be handed off to Development.

The fact that few companies take the time for this level of user analysis explains why so many products either don't solve user problems (poor "usefulness") or fail because they're too hard to learn and use (poor "usability").

It also explains why user documentation often fails. Lacking adequate user scenarios, technical writers typically create their deliverables from specifications and beta interfaces. They document how a product works, but not why. They explain how to perform tasks in an interface, but not when a user might need to do those tasks. They describe user options in abstract or generic terms, but don't help the user decide which option to choose.

A client I'm working for now is a good example. The technical writer has done a very good job of explaining the components of the interface, but nothing about how they relate to users' real world business problems. The data is described as a developer might understand it, but not in terms of what users need to do with it. As a result, the user guide is essentially useless in teaching me what I need to know to create user training.

When I asked the subject matter expert about this, she said: "The user doc explains what's there but not why you'd use it. That's what the training has to get across."

When was the last time you learned a new software tool just by reading the user manual or help?

Another illustration: I remember hearing a quote from a manager responsible for a popular income tax software product. In regard to the product's help, she said "My problem is not teaching people how to use the software, it's teaching people how to think like accountants." In other words, the help needed to impart domain knowledge, to assist users in knowing which options they needed to choose.

For many years we've been hearing that user manuals and help are miserable, that they "don't really help people." I think this is the biggest reason why. I see real world examples and domain knowledge as the missing span in most user documentation.

So what's the fix? More on this in a later post.

Tuesday, September 2, 2008

Achieving Good Flow in Your Writing and Speaking

To promote my coaching practice, I write occasional articles on general business communication issues. How to write effective emails, how to give good presentations, and so on. I whimsically call these "Thoth's Tips", after the Egyptian god of scribes and wisdom.

I've just posted a new Thoth's Tip on my website. The subject is how to achieve good flow in written and spoken communication. Flow may be a mysterious quality, but Thoth does have a few suggestions on how to make flow your friend.