When you deploy a new or updated application, you’ll spend less time and money answering help desk calls from frustrated users if you spend time and money creating good documentation.
What makes the difference between good documentation and bad documentation? In my article "Reduce help desk calls by writing to the right audience," I talked about the importance of avoiding technical jargon and using a top-down approach when writing step-by-step instructions. In this column, I’d like to recommend the three questions you must answer when you document an application for end users.
The big three
A small custom software company recently contracted me to write documentation for the second version of an application developed for school administrators and teachers. I wrote one soup-to-nuts document that illustrated and explained almost every single menu pick, dialog box, and process needed by the administrators.
The documentation for the teachers was another matter. Going in to the project, we knew that many of the teachers weren't computer-literate. They were interested in learning only what was necessary to maintain student attendance records and grades.
To help eliminate the need for extensive training and technical support calls, I decided to outline the documentation for the teachers by answering three questions:
- Who is using the application?
- What tasks does the user need to accomplish with the application?
- Do the instructions work as published?
Who is using the application?
When you write a users’ manual, you must put yourself in the shoes of the people who are going to be reading and using your documentation. In this case, the people using the application are teachers, some who are computer-literate, and some who are not.
To help remind myself of my audience, I printed a sheet with the words “Teachers at work” in 48-point typeface and hung that sheet on my desktop. I used that poster as a reminder that my audience, like the software I was documenting, had a very specific mission. If I found myself writing about a process that only the administrators needed to perform, or if I caught myself using nonessential technical jargon, I deleted those sections.
What tasks does the user need to accomplish?
I’m a big fan of task-oriented training and task-oriented documentation. If you’re having trouble trying to figure out what you should put into your user documentation, start a list of things the user will do with the software. Then, when you write the outline that will become your table of contents, be sure to use language that is task-oriented and specific.
For example, the developer thinks of his program as doing things like adding and updating records. However, those phrases don’t mean much to the end user who is thumbing through the table of contents or the index, wondering where the instructions are for adding a new student or entering a grade.
To keep the writing focused on tasks, the outline for my document included titles like this:
- How to enter a grade
- How to take attendance
- How to schedule an activity
If you’re documenting a custom accounts payable application, your task-oriented outline might have sections like this:
- How to set up a vendor
- How to enter an invoice
- How to record a payment or credit
Instead of starting with your application’s first menu option and documenting all possible choices as they appear in the application interface, make a list of tasks. Use that list of tasks as your outline.
Do the instructions work as published?
I saved the most important step of writing documentation for last. It’s the one thing that technologists and technical writers most often forget to do. After you write the documentation, try it out. (Or better yet, ask someone else to try it out for you.)
Don’t assume that you’ve written error-free, unambiguous instructions. Prove it to yourself. Start on page one of your document, and try to do everything you’ve instructed your customers to do, exactly as you’ve written it. Chances are you’ll uncover at least a couple of instructions that are vague, ambiguous, or just plain incorrect.
By taking time on the front end to confirm each and every instruction in your document, you’ll have fewer calls from confused end users on the back end.
Share your favorite documentation tips
Do you document applications for end users? Share your experiences with fellow TechRepublic members by posting a comment or writing to Jeff.