Software User Manuals

A comprehensive set of software user manuals helps improve user acceptance of a new online tool for managing complex administrative tasks.

Tools Used: MS Word, Adobe Acrobat, SnagIt

The Canadian Quality Milk (CQM) program works to maintain food safety on dairy farms through improved management practices, increased communication among stakeholders, and effective record-keeping.

    The program entails:
  • regular reporting by dairy producers on their production environment and procedures.
  • training and follow-up assessments by CQM personnel at the local and provincial levels.
  • regular reporting by all levels up to a national governing level.

To manage the record-keeping, the Dairy Farmers of Canada developed an online task-management and document-management system designed to help streamline the administrative tasks of the CQM program.


Lots of content; nervous users

The new online system was replacing traditional paper-based record-keeping. It contained a very large number of workflows, all of which needed to be documented with step-by-step instructions.

Many users were not at all comfortable using computers or web-based applications. User resistance was therefore a big concern: users would resist adopting the new system if they perceived that it was difficult to use.

The program coordinator consequently approached me about developing a clear, straight-forward software user manual that would help users migrate painlessly to the new system and use it willingly to accomplish their routine tasks.


Divide and conquer

A key strategy was to divide the documentation into multiple user manuals. Each manual is aimed at a specific user group and contains only the workflows and procedures relevant to that group.

Dividing the content keeps each manual to a reasonable size, which helps dispel the perception that the system is difficult to use.

All the manuals were developed using a single custom-built Microsoft Word template, providing a consistent appearance and style that reflects the branding of the CQM program and the online system.


Design for usability

Thoughtful design helps make the manuals easier to use and mitigates the resistance felt by users who are uncomfortable with using an online system.

Within each manual, workflows are grouped into broad, task-oriented categories.

Users can easily navigate through the document and find the procedure they need to accomplish a specific task.

Instructions are written with nervous users in mind.

A brief context statement helps users decide if the procedure applies to the task they need to do.

Detailed step-by-step instructions guide users through the procedure.

Acurate screenshots help users work with the system and provide reassurance that instructions have been followed correctly.

This Can Work for You, Too

Change can be difficult to manage. People often resist adopting a new tool or process, even when it will ultimately make their jobs easier. Whether you are trying to improve efficiency within your own organization or sell your product to customers, this resistance to change is bad news: no matter how good the product or tool is, it's worthless if you can't convince people to use it.

Providing a quality user manual for a tool—be it software, machinery, an electronic device, or anything else—can spell the difference between success or failure when that tool is rolled out to users.

Quality documentation takes time to produce. Plan for this early on in the development phase so that your product launch is not delayed by the lack of a decent manual. Ideally, you should plan and produce the user manual at the same time as you are developing the tool, so that the manual is ready to go when the tool is.

Be sure to hand the task of creating the user manual to someone who has the skills required to produce clear, audience-focused content: Solid writing skills, the ability to evaluate the most effective way of presenting information (e.g., traditional print documentation, online help, etc.), and in-depth knowledge of applications required to produce the documentation (MS Word, Adobe Acrobat, Visio or XML authoring tools, etc.).

If you have people with these skills in your organization already, you're ahead of the game. If you don't and would like to develop these skills in-house, check out the technical writing workshops that I offer. These workshops can help your technical staff identify exactly what the users will need to know and produce documentation that delivers it. On the other hand, if you'd rather just hire someone to take care of the documentation for you, give me a call. I can help.