Sunday, January 11, 2009

Help! I don't understand!


I am often frustrated trying to read a manual or using online Help – it’s difficult to understand, or it just doesn’t address my problem. And yet, I’ve been writing software documentation for Axon Development Corporation for the past five years so I know just how challenging it can be to write useful documentation.

Axon provides Canadian and US trucking companies with an integrated trucking and accounting software package. It covers everything from choosing a delivery route, to paying drivers, to sending out invoices, and evaluating profit and loss. Axon upgrades its software weekly so the documentation is constantly being revised. It’s a complex but fascinating task.

No one person at Axon can give me all the information I need to write the documentation. I learn the details of new features from the programmers, but I find out exactly how the customers use the program and the problems they’re having by talking to the support staff.

It’s often a balancing act between what the programmers consider to be best practices and how customers actually use the software. I’m an intermediary between Axon staff and their customers as I can appreciate both perspectives.

Technical writing is precise and methodical. It’s a little like a jigsaw puzzle as you carefully piece the words together so that the user will understand what you’re trying to say. You often need to provide the information in more than one way and in more than one location.
Axon provides both field-by-field explanations of how to most effectively use the system and How Do I that provide step-by-step instructions on how to complete a function (e.g. How do I create a check by Direct Deposit?). We also provide timesaving and troubleshooting tips (e.g. keyboard shortcuts and explanations for error messages).

User statistics indicate that new customers are the biggest users of Axon’s Help. As a result, we’ve tailored a lot of the Help to beginners, explaining how to move around in the system, providing a checklist of the tasks that need to be done as soon as they go live, and providing them with lots of How Do I for the most common initial tasks (How do I set up a satellite interface? How do I process a regular payroll run?).

It’s more difficult to assist the experienced users as they have very specific questions that are unique to their company’s situation. We know they are frequently preparing Reports so we’ve enhanced the help by providing examples of how to fill in the fields in order to obtain specific kinds of information.

Over time Axon staff have come to rely on the Help to provide them with detailed information about how to do certain tasks. And they are now championing the Help, recommending it to their clients and requesting revisions and additions so that they don’t have to verbally explain the same thing over and over again to different customers. That for me is a sure sign of success.
My sincere thanks to Axon's owners and staff who are awesome to work with.

No comments: